Design tokens
Tokens are DTCG-compatible JSON transformed into CSS custom properties with Style Dictionary. They keep visual decisions named, portable, and consistent across native Web Components, React, Vue, and the documentation site.
Tailwind v4 applications can consume the same runtime contract through the generated @aidsgn/tokens/tailwind.css integration instead of duplicating token values in application configuration.
Authored paths use the aidsgn root namespace, such as aidsgn.color.text.primary. Generated CSS converts dot-separated paths into kebab-cased custom properties such as --aidsgn-color-text-primary.
Token layers
Section titled “Token layers”Primitive tokens define the system’s raw visual vocabulary as systematic palettes and scales. Semantic tokens name the purpose of a value and directly alias a primitive. Components consume semantic tokens for public visual intent, so themes can change the primitive choice without changing component CSS.
.example { color: var(--aidsgn-color-text-primary); background: var(--aidsgn-color-surface-default); border-radius: var(--aidsgn-control-radius);}Categories
Section titled “Categories”| Category | What it controls |
|---|---|
| Color | Perceptual palettes, semantic roles, themes, and contrast. |
| Spacing | Gaps, padding, rhythm, and bounded responsive composition. |
| Radius | Corner shape and the visual character of containers and controls. |
| Typography | Complete fluid type recipes for headings, body text, and labels. |
| Shadow | Restrained elevation for controls, containers, and floating surfaces. |
| Motion | Shared durations and easing curves for coordinated transitions. |
| Semantic tokens | Intent-based aliases consumed by components and overridden by themes. |
| Creating themes | Brand primitives, mode overrides, delivery, and verification. |
Authorship rules
Section titled “Authorship rules”Every token includes $value, $type, and $description. Descriptions explain intended use, acceptable contexts, and accessibility constraints. Raw values belong only to primitive category files. Semantic and theme values must directly reference a primitive.
The Style Dictionary build validates that boundary, type compatibility, required palette steps and lightness order, and verifies theme paths override an existing semantic token. It emits labeled primitive and semantic sections, and semantic CSS variables retain their relationship as var(--aidsgn-primitive-token) references.
Generated CSS is build output and must not be edited directly. Change the JSON in packages/tokens/src, build @aidsgn/tokens, and review the category previews on this site.
The committed Tailwind adapter is a Style Dictionary platform output emitted alongside the runtime CSS bundles from the same resolved token dictionary. Repository contributors run pnpm tailwind:generate after relevant token changes; pnpm tailwind:check rejects stale output.