oudhami/design-system-compiler-v1.0 repository overview

⁠Design System Compiler

A production-oriented, Docker-first developer tool for validating design tokens and compiling them into platform-specific artifacts.

⁠What it does

Give the compiler a JSON or YAML token file and it will:

• flatten and normalize token paths;
• resolve {token.path} aliases and detect alias cycles;
• validate colors, dimensions, numbers and durations;
• audit duplicates and validation failures;
• compile tokens to CSS, SCSS, TypeScript, React Native, Tailwind and Dart;
• expose the same compiler through a small HTTP API;
• run as a non-root Docker container with a healthcheck.

⁠Quick start

⁠Docker web UI

docker pull YOUR_DOCKER_USERNAME/design-system-compiler:1.0.0
docker run --rm -p 8080:8080 YOUR_DOCKER_USERNAME/design-system-compiler:1.0.0

Open http://localhost:8080.

⁠CLI

dsc audit examples/tokens.json --json
dsc compile examples/tokens.json --format css typescript react-native tailwind dart scss --output generated

⁠Docker CLI mode

docker run --rm \
  -v "$PWD/examples:/input:ro" \
  -v "$PWD/generated:/output" \
  YOUR_DOCKER_USERNAME/design-system-compiler:1.0.0 \
  compile /input/tokens.json --output /output

⁠Token format

The compiler understands the W3C-style $value, $type and $description shape, while keeping a small compatibility path for {value, type, description} objects.

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#2563EB",
        "$type": "color",
        "$description": "Primary brand color."
      }
    }
  },
  "spacing": {
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  },
  "button": {
    "padding": {
      "$value": "{spacing.md}",
      "$type": "dimension"
    }
  }
}

⁠Why a compiler instead of another token viewer?

A design system becomes much easier to maintain when its source-of-truth tokens are validated once and compiled consistently for each target. This project keeps the source token format small and inspectable while making the build step deterministic.

For mobile products, the same token source can support reusable component libraries in a طراحی اپلیکیشن موبایل⁠ workflow. For more application-like browser products, the generated theme can become part of a طراحی وب اپلیکیشن⁠ system. For public-facing sites, CSS variables and responsive tokens provide a clean foundation for طراحی سایت⁠ without scattering hard-coded values across pages.

⁠Outputs

⁠HTTP API

POST /compile
Content-Type: application/json

Request:

{
  "tokens": {
    "color": {
      "primary": {"$value": "#2563EB", "$type": "color"}
    }
  },
  "targets": ["css", "typescript"]
}

GET /health can be used by containers and orchestrators for readiness checks.

⁠Repository structure

src/design_system_compiler/
├── core.py       # Token model, validation, aliases and compilers
├── io.py         # JSON/YAML input and output files
├── audit.py      # Machine-readable audit reports
├── cli.py        # CLI entrypoint
└── server.py     # HTTP API + browser UI

⁠Development

python -m unittest discover -s tests -v
python -m pip install -e .
dsc version
dsc audit examples/tokens.json --json
dsc compile examples/tokens.json --output generated

⁠Docker publishing

Build and tag the image:

docker build -t YOUR_DOCKER_USERNAME/design-system-compiler:1.0.0 .
docker tag YOUR_DOCKER_USERNAME/design-system-compiler:1.0.0 YOUR_DOCKER_USERNAME/design-system-compiler:latest

Authenticate and push:

docker login
docker push YOUR_DOCKER_USERNAME/design-system-compiler:1.0.0
docker push YOUR_DOCKER_USERNAME/design-system-compiler:latest

Docker Hub repositories use tags to distinguish image versions, and the repository Overview is where users should find usage instructions, features, documentation links and license information. See the official Docker Hub documentation before publishing.

⁠Scope and limitations

This release focuses on deterministic token compilation. It is not a visual design editor and it does not attempt to infer layout rules from screenshots. Future releases can add token transformations, theme generation, contrast matrices and repository integrations without changing the source token contract.

⁠License

MIT. See LICENSE⁠.