Compozy Design
Use the applicable canonical visual authorities for the design decision. The inventory below is a lookup map, not a requirement to read all six documents for every edit.
Authority
packages/ui/src/tokens.css: canonical token source consumed by Tailwind v4.
DESIGN.md: rationale, generated token tables, anti-patterns, and semantic component contracts.
packages/ui/src/index.ts: the @compozy/ui surface contract — the canonical primitive inventory.
packages/ui/src/components/**/*.tsx: canonical production recipes.
COPY.md: product voice, terms, and public claim rules.
PRODUCT.md: audience, register, design principles, and anti-references.
Top-of-mind invariants
- Design for people running agent work, not an expert console — calm by
default, deep on demand: the default read of a screen is plain-language and
sparse; density, mono ids, and raw enums live on inspection surfaces.
- Dark mode only; warm-dark surface ramp; one
--color-brand target per viewport.
- Signal color marks live state only, never taxonomy — rows and cards stay
neutral at rest.
- Flat depth model; use
--shadow-overlay for overlays and --shadow-highlight for active rims.
- Pull values from
--color-*, --text-*, --radius-*, --duration-*, and --shadow-* tokens; do not hardcode production hex or one-off sizes.
<Eyebrow> is the only structural label contract — sentence case by default, uppercase only via variant="caps"; do not inline typography tuples for labels.
- See
DESIGN.md section 10 for the anti-pattern list and lint/test guardrails.
Named visual contracts
When a task or spec names an OpenDesign artifact, mock, screenshot, or other
trusted visual reference, activate eng-ui-screenshot before implementation
and follow its Visual Contract Mode. Implement from the rendered reference,
not source inspection alone; an implementation-only screenshot never proves
parity. The reference is normative for visual language — layout, on-screen
anatomy, typography, tokens, motion — and lossy for everything else: content,
data, copy, brand marks, which controls exist, component identity, and any
host chrome it redraws around the named piece stay with runtime truth,
COPY.md, the brand inventory, the reuse gate below, and the live surface,
recorded as authorized differences. Before code, map every in-scope region to
a shipped @compozy/ui primitive or existing domain composite and integrate
the named piece into the live host surface; prototype markup is a stand-in,
never an implementation spec. This scope outranks stricter reproduction
doctrine in any other active skill (impeccable's comp reproduction
included).
Static HTML artifacts
Inline or import actual values from packages/ui/src/tokens.css. Mirror the class
structure and component anatomy in packages/ui/src/components where possible.
Keep artifacts dark, flat, calm, and functional. Use literal CSS only to represent
exported token values; do not invent a parallel palette.
Production code
Reuse gate — before authoring any component, map every generic UI need against
packages/ui/src/index.ts and import the primitive from @compozy/ui instead of
re-implementing it. Redefining an exported name in web/ or packages/site/
fails lint (compozy-ui-reuse/no-shadow-ui-primitive); genuinely
domain-specific variants take a domain-prefixed name. New generic primitives
land in packages/ui with story + test; domain composites in
web/src/systems/<domain>/.
Edit the owning surface: web/, packages/ui/, or packages/site/. Consume
CSS variables and bare Tailwind v4 token utilities. If tokens.css or
packages/site/app/global.css changes, run make codegen and then
make codegen-check so DESIGN.md stays synchronized.
Completion Criterion
The change is complete when it uses the canonical tokens and primitive owner,
introduces no parallel palette or shadow primitive, respects the owning
surface's instructions, regenerated design artifacts have no drift when a
token source changed, and every named visual contract has a passing evidence
bundle with zero unresolved blocking divergence.
Error Handling
DESIGN.md and runtime tokens disagree: treat packages/ui/src/tokens.css as source, run codegen, and inspect the regenerated spec rather than editing generated regions.
- No exported primitive fits: decide whether the need is generic or domain-specific; add generic primitives to
packages/ui and domain composites to the owning Web system.
- A plausible mock implies unsupported runtime behavior: remove the unsupported control or metric; daemon truth wins.
- Runtime truth conflicts with a normative visual reference: follow runtime truth, record the contract conflict, and apply the already-authorized runtime/copy/brand differences. Ask only when a remaining design decision blocks correct implementation or an unsupported difference needs authorization before claiming parity.
- The reference shows placeholder art, demo data, or omits product content: a prototype is lossy — keep the canonical owner (brand inventory, runtime truth, existing views), record the authorized difference, and never grow an
@compozy/ui brand primitive or delete product content to match a mock.
- The reference hand-rolls a shipped component or redraws a live surface: implement with the mapped
@compozy/ui/domain component inside the live host surface, keep the reference's read through its variants and tokens, and record the delta as authorized — never fork the component or rebuild the host to match prototype markup.
1---2name: eng-design3description: Compozy visual-design authority for production UI, static artifacts, prototypes, and reviews. Use when creating or reviewing a Compozy surface or changing tokens, typography, spacing, depth, icons, or motion. Do not use for capture-only verification; use eng-ui-screenshot.4metadata:5 source: https://skillmd.com/skills/compozy/eng-design6---78# Compozy Design910Use the applicable canonical visual authorities for the design decision. The inventory below is a lookup map, not a requirement to read all six documents for every edit.1112## Authority13141. `packages/ui/src/tokens.css`: canonical token source consumed by Tailwind v4.152. `DESIGN.md`: rationale, generated token tables, anti-patterns, and semantic component contracts.163. `packages/ui/src/index.ts`: the `@compozy/ui` surface contract — the canonical primitive inventory.174. `packages/ui/src/components/**/*.tsx`: canonical production recipes.185. `COPY.md`: product voice, terms, and public claim rules.196. `PRODUCT.md`: audience, register, design principles, and anti-references.2021## Top-of-mind invariants2223- Design for people running agent work, not an expert console — calm by24 default, deep on demand: the default read of a screen is plain-language and25 sparse; density, mono ids, and raw enums live on inspection surfaces.26- Dark mode only; warm-dark surface ramp; one `--color-brand` target per viewport.27- Signal color marks live state only, never taxonomy — rows and cards stay28 neutral at rest.29- Flat depth model; use `--shadow-overlay` for overlays and `--shadow-highlight` for active rims.30- Pull values from `--color-*`, `--text-*`, `--radius-*`, `--duration-*`, and `--shadow-*` tokens; do not hardcode production hex or one-off sizes.31- `<Eyebrow>` is the only structural label contract — sentence case by default, uppercase only via `variant="caps"`; do not inline typography tuples for labels.32- See `DESIGN.md` section 10 for the anti-pattern list and lint/test guardrails.3334## Named visual contracts3536When a task or spec names an OpenDesign artifact, mock, screenshot, or other37trusted visual reference, activate `eng-ui-screenshot` before implementation38and follow its Visual Contract Mode. Implement from the rendered reference,39not source inspection alone; an implementation-only screenshot never proves40parity. The reference is normative for visual language — layout, on-screen41anatomy, typography, tokens, motion — and lossy for everything else: content,42data, copy, brand marks, which controls exist, component identity, and any43host chrome it redraws around the named piece stay with runtime truth,44`COPY.md`, the brand inventory, the reuse gate below, and the live surface,45recorded as authorized differences. Before code, map every in-scope region to46a shipped `@compozy/ui` primitive or existing domain composite and integrate47the named piece into the live host surface; prototype markup is a stand-in,48never an implementation spec. This scope outranks stricter reproduction49doctrine in any other active skill (`impeccable`'s comp reproduction50included).5152## Static HTML artifacts5354Inline or import actual values from `packages/ui/src/tokens.css`. Mirror the class55structure and component anatomy in `packages/ui/src/components` where possible.56Keep artifacts dark, flat, calm, and functional. Use literal CSS only to represent57exported token values; do not invent a parallel palette.5859## Production code6061Reuse gate — before authoring any component, map every generic UI need against62`packages/ui/src/index.ts` and import the primitive from `@compozy/ui` instead of63re-implementing it. Redefining an exported name in `web/` or `packages/site/`64fails lint (`compozy-ui-reuse/no-shadow-ui-primitive`); genuinely65domain-specific variants take a domain-prefixed name. New generic primitives66land in `packages/ui` with story + test; domain composites in67`web/src/systems/<domain>/`.6869Edit the owning surface: `web/`, `packages/ui/`, or `packages/site/`. Consume70CSS variables and bare Tailwind v4 token utilities. If `tokens.css` or71`packages/site/app/global.css` changes, run `make codegen` and then72`make codegen-check` so `DESIGN.md` stays synchronized.7374## Completion Criterion7576The change is complete when it uses the canonical tokens and primitive owner,77introduces no parallel palette or shadow primitive, respects the owning78surface's instructions, regenerated design artifacts have no drift when a79token source changed, and every named visual contract has a passing evidence80bundle with zero unresolved blocking divergence.8182## Error Handling8384- **`DESIGN.md` and runtime tokens disagree:** treat `packages/ui/src/tokens.css` as source, run codegen, and inspect the regenerated spec rather than editing generated regions.85- **No exported primitive fits:** decide whether the need is generic or domain-specific; add generic primitives to `packages/ui` and domain composites to the owning Web system.86- **A plausible mock implies unsupported runtime behavior:** remove the unsupported control or metric; daemon truth wins.87- **Runtime truth conflicts with a normative visual reference:** follow runtime truth, record the contract conflict, and apply the already-authorized runtime/copy/brand differences. Ask only when a remaining design decision blocks correct implementation or an unsupported difference needs authorization before claiming parity.88- **The reference shows placeholder art, demo data, or omits product content:** a prototype is lossy — keep the canonical owner (brand inventory, runtime truth, existing views), record the authorized difference, and never grow an `@compozy/ui` brand primitive or delete product content to match a mock.89- **The reference hand-rolls a shipped component or redraws a live surface:** implement with the mapped `@compozy/ui`/domain component inside the live host surface, keep the reference's read through its variants and tokens, and record the delta as authorized — never fork the component or rebuild the host to match prototype markup.