use-agentz 0.1.0

package/registry/r/skill.design-system.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "name": "design-system",
+  "type": "skill",
+  "title": "design-system",
+  "description": "Design token architecture and component specification. Use when creating or maintaining design tokens, CSS variables, themes, dark mode, color palettes, component specs (button, input, card, badge, alert, dialog, table), interaction states, Tailwind or shadcn theming, brand-guidelines-to-token sync, WCAG contrast checks, or typography scales. Load design-taste alongside as the aesthetic foundation.",
+  "dependencies": [
+    "skill:design-taste",
+    "tool:contrast-check",
+    "tool:token-validate"
+  ],
+  "files": [
+    {
+      "path": "SKILL.md",
+      "content": "---\nname: design-system\ndescription: >\n  Design token architecture and component specification. Use when creating or\n  maintaining design tokens, CSS variables, themes, dark mode, color palettes,\n  component specs (button, input, card, badge, alert, dialog, table),\n  interaction states, Tailwind or shadcn theming, brand-guidelines-to-token\n  sync, WCAG contrast checks, or typography scales. Load design-taste alongside\n  as the aesthetic foundation.\nrequires: [design-taste]\n---\n\n# Design System\n\nBuild and maintain token-driven UIs: three token layers, exact component\nspecs, state rules, Tailwind/shadcn wiring, brand sync, contrast math, type\nscale. Never hardcode a color, size, or duration a token already names.\n\nPrecedence: product screens: product-ui > design-system > design-taste.\nMarketing/visual: design-taste > design-system. Tools (design-lint etc.) are\nadvisory heuristics; a skill rule beats a tool WARN, and a deliberate\ndocumented choice beats both.\n\nGreenfield: pick palette + font pairing (design-search) -> define primitives\n-> semantic aliases -> dark overrides -> component tokens -> contrast-check\nall pairs -> wire Tailwind vars -> token-validate clean.\nExisting project: token-validate inventory -> map each hardcoded value to a\nprimitive -> introduce semantic layer -> rewrite components layer by layer ->\nenforce with token-validate in review.\n\n## Three-layer architecture\n\n| Layer | Purpose | Change cadence | Example |\n|---|---|---|---|\n| Primitive | Raw values, no opinion | Rarely | `--color-blue-600: #2563EB` |\n| Semantic | Purpose aliases, theming | On theme switch | `--color-primary: var(--color-blue-600)` |\n| Component | Per-component overrides | Per component | `--button-bg: var(--color-primary)` |\n\nNaming: `--{category}-{item}-{variant}-{state}`. Categories: color, space,\nfont-size, radius, shadow, duration. Examples: `--color-primary-hover`,\n`--button-bg-hover`, `--space-section-sm`.\n\nConsumption rule: components consume SEMANTIC tokens or their OWN component\ntokens, never primitives. Good: `.card { background: var(--color-card) }`.\nBad: `.card { background: var(--color-gray-50) }`.\n\nDark mode: override SEMANTIC tokens only, under `.dark`. Never fork primitives\nor component tokens per theme. Exact overrides:\n\n| Semantic token | Light | Dark override |\n|---|---|---|\n| background | gray-50 | gray-950 |\n| foreground | gray-900 | gray-50 |\n| card, popover | white | gray-900 |\n| muted, secondary, accent | gray-100 | gray-800 |\n| muted-foreground | gray-500 | gray-400 |\n| border, input | gray-200 | gray-800 |\n\nFile org: `tokens/{primitives,semantic,components}.css` plus index, or one\nfile with `=== PRIMITIVES / SEMANTIC / COMPONENTS / DARK MODE ===` sections.\n\n## Primitive catalog\n\nThese illustrate scale SHAPE, not recommended values. Seed real primitives\nfrom design-search (--domain color, 192 product palettes) and hand-tune;\nshipping the stock Tailwind gray/blue palette is the statistical-default look\ndesign-taste exists to break.\n\nGray: 50 #F9FAFB, 100 #F3F4F6, 200 #E5E7EB, 300 #D1D5DB, 400 #9CA3AF,\n500 #6B7280, 600 #4B5563, 700 #374151, 800 #1F2937, 900 #111827, 950 #030712.\nBlue: 50 #EFF6FF, 100 #DBEAFE, 200 #BFDBFE, 300 #93C5FD, 400 #60A5FA,\n500 #3B82F6, 600 #2563EB, 700 #1D4ED8, 800 #1E40AF, 900 #1E3A8A.\nStatus: green-500 #22C55E, green-600 #16A34A; yellow-500 #EAB308,\nyellow-600 #CA8A04; red-500 #EF4444, red-600 #DC2626; info = blue-500.\n\nSpacing (4px base, px values): 0, px=1, 0.5=2, 1=4, 1.5=6, 2=8, 2.5=10, 3=12,\n3.5=14, 4=16, 5=20, 6=24, 7=28, 8=32, 9=36, 10=40, 12=48, 14=56, 16=64,\n20=80, 24=96.\n\nFont size: xs 12, sm 14, base 16, lg 18, xl 20, 2xl 24, 3xl 30, 4xl 36,\n5xl 48px. Line height: none 1, tight 1.25, snug 1.375, normal 1.5,\nrelaxed 1.625, loose 2. Weight: 400 normal, 500 medium, 600 semibold,\n700 bold. Tracking: tighter -0.05em, tight -0.025em, normal 0, wide 0.025em,\nwider 0.05em.\n\nRadius: none 0, sm 2, default 4, md 6, lg 8, xl 12, 2xl 16, 3xl 24,\nfull 9999px.\n\n| Shadow | Recipe |\n|---|---|\n| sm | 0 1px 2px 0 rgb(0 0 0 / 0.05) |\n| default | 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1) |\n| md | 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1) |\n| lg | 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1) |\n| xl | 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1) |\n| 2xl | 0 25px 50px -12px rgb(0 0 0 / 0.25) |\n| inner | inset 0 2px 4px 0 rgb(0 0 0 / 0.05) |\n\nTint shadows toward the background hue (desaturated, low alpha) instead of\npure black, especially on colored/warm backgrounds; pure-black rgba is\nacceptable in neutral-gray product UI.\n\nDurations: 75, 100, 150, 200, 300, 500, 700, 1000ms. Semantic: fast=150,\nnormal=200, slow=300. Z-index: content 0-50 in tens; dropdown 1000,\nsticky 1100, modal 1200, popover 1300, tooltip 1400.\n\n## Semantic tokens\n\n| Token | Value | Foreground / states |\n|---|---|---|\n| background | gray-50 | foreground = gray-900 |\n| card | white | gray-900 |\n| popover | white | gray-900 |\n| primary | blue-600 | white; hover blue-700, active blue-800 |\n| secondary | gray-100 | gray-900; hover gray-200 |\n| muted | gray-100 | gray-500 |\n| accent | gray-100 | gray-900 |\n| destructive | red-600 | white; hover red-700 |\n| success | green-600 | white |\n| warning | yellow-500 | gray-900 |\n| error | red-600 | white |\n| info | blue-500 | white |\n| border, input | gray-200 | - |\n| ring | blue-500 | ring-width 2px, ring-offset 2px |\n\nprimary=blue-600 here illustrates scale shape, not a recommended value; seed\nreal primitives from design-search (--domain color) and hand-tune.\nPure white card/popover surfaces on a tinted background are fine in product\nUI; page-level backgrounds and marketing surfaces follow design-taste\n(off-white/off-black).\n\nSpacing semantics: component-xs=space-1, component-sm=2, component=3,\ncomponent-lg=4; section-sm=8, section=12, section-lg=16; page-x=4, page-y=6.\nTypography semantics: heading=2xl, heading-lg=3xl, heading-xl=4xl; body=base,\nbody-sm=sm, body-lg=lg; label=sm; caption=xs. opacity-disabled = 0.5.\n\n## Component tokens and specs\n\nPattern: each component consumes only its own vars, which alias semantics:\n\n```css\n.button {\n  background: var(--button-bg);       /* -> var(--color-primary) */\n  color: var(--button-fg);\n  transition: background var(--duration-fast);\n}\n.button:hover { background: var(--button-bg-hover); }  /* primary-hover */\n```\n\nButton. Variants: default primary/white; secondary gray-100/gray-900; outline\ntransparent + 1px border, hover bg accent; ghost transparent, hover accent;\nlink text primary; destructive red-600/white. Radius md, weight medium.\nAnatomy: [leading icon] label [trailing icon].\n\n| Size | Height | Padding | Font | Icon |\n|---|---|---|---|---|\n| sm | 32 | 12x6 | 14 | 16 |\n| default | 40 | 16x8 | 14 | 18 |\n| lg | 48 | 24x12 | 16 | 20 |\n| icon-only | 40x40 | - | - | 18 |\n\nInput. Sizes: sm h32 px12 py8 f14; default h40 px12 py8 f14; lg h48 px16 py12\nf16. States: default border gray-300; hover gray-400; focus border primary +\nring primary/20%; error border red-500 + ring red/20%; disabled border\ngray-200, bg gray-100. Anatomy: label above, [icon] value [action], helper or\nerror text below. Placeholder = muted-foreground.\n\nCard. Variants: default shadow-sm + 1px border; elevated shadow-lg, no\nborder; outline border only; interactive shadow-sm to md on hover. Radius lg.\nPadding: header 24 24 0, content 24, footer 0 24 24; internal gap 16.\n\nBadge. Radius full. Sizes: sm px8 py4 f11 h20; default px10 py4 f12 h24;\nlg px12 py6 f14 h28. Variants: default primary/white, secondary, outline,\ndestructive, success green-600/white, warning yellow-500/gray-900.\n\nAlert. Padding 16, radius lg. Variants: default gray-50 bg + gray-200 border;\ndestructive red-50/red-200; success green-50/green-200; warning\nyellow-50/yellow-200.\n\nDialog. Widths: sm 384, default 512, lg 640, xl 768px; mobile full =\n100% - 32px. Overlay rgb(0 0 0 / 0.5), padding 24, radius lg, shadow lg.\n\nTable. Header bg muted, fg muted-foreground. Cell padding 12x16 (y-x). Row\nheights: compact 40, default 48, comfortable 56. Row states: hover gray-50,\nselected primary at 10%, striped gray-50/white. Alignment: text left, numbers\nRIGHT, status/badge center, actions right.\n\n## States\n\nPriority, high to low: disabled > loading > active > focus > hover > default.\nHigher state suppresses lower.\n\n| Property | Duration | Easing |\n|---|---|---|\n| color, background | 150ms | ease-in-out |\n| transform | 200ms | ease-out |\n| opacity | 150ms | ease |\n| box-shadow | 200ms | ease-out |\n\nStandard transition: `transition-property: color, background-color,\nborder-color, box-shadow; transition-duration: var(--duration-fast);\ntransition-timing-function: ease-in-out;`\n\nFocus ring: keep a transparent real outline for fallback, then a double\nbox-shadow; inner 2px = background color (fake offset), outer +2px = ring\ncolor. `focus-within` for containers. The transparent `outline` preserves\nWindows High Contrast Mode (which ignores box-shadow) and keeps a11y\nheuristics from misreading an `outline: none` line.\n\n```css\n:focus-visible {\n  outline: 2px solid transparent;\n  outline-offset: 2px;\n  box-shadow: 0 0 0 2px var(--color-background), 0 0 0 4px var(--color-ring);\n}\n```\n\nNever remove focus indication; this replaces the ring visual, not the\naffordance.\n\nDisabled: opacity 0.5, pointer-events none, cursor not-allowed, bg muted, fg\nmuted-foreground. Set both `disabled` attr and `aria-disabled`. Keep 3:1\ncontrast even when disabled.\n\nLoading placement: button = replace leading icon or center spinner; input =\ntrailing spinner; card = centered overlay; page = viewport center. Dim\ncontent to opacity 0.7. Add `aria-busy` plus sr-only loading text.\n\nError recipe: input border red-500; focus = double shadow 2px background +\n4px error color; helper text red-600 below field with icon (never color\nalone); `aria-invalid` on input, message `role=\"alert\"`; clear on valid.\n\nContrast floors: normal text 4.5:1, large text (18px+) 3:1, UI components\n3:1, focus indicator 3:1.\n\n## Tailwind / shadcn integration\n\nHSL space-separated triplets, NO hsl() wrapper. Enables opacity modifiers:\n`bg-primary/50` compiles to `hsl(217 91% 60% / 0.5)`.\n\n```css\n@layer base {\n  :root {\n    --background: 0 0% 100%; --foreground: 222 47% 11%;\n    --primary: 217 91% 60%; --primary-foreground: 0 0% 100%;\n    --secondary: 220 14% 96%; --muted: 220 14% 96%; --accent: 220 14% 96%;\n    --muted-foreground: 220 9% 46%; --destructive: 0 84% 60%;\n    --border: 220 13% 91%; --input: 220 13% 91%; --ring: 217 91% 60%;\n    --radius: 0.5rem;\n  }\n  .dark {\n    --background: 222 47% 4%; --foreground: 210 40% 98%;\n    --secondary: 217 33% 17%; --muted: 217 33% 17%; --accent: 217 33% 17%;\n    --muted-foreground: 215 20% 65%; --destructive: 0 62% 30%;\n    --border: 217 33% 17%; --input: 217 33% 17%;\n  }\n}\n```\n\n```ts\n// tailwind.config.ts\ndarkMode: ['class'],\ncolors: {\n  background: 'hsl(var(--background))',\n  primary: { DEFAULT: 'hsl(var(--primary))',\n             foreground: 'hsl(var(--primary-foreground))' },\n  // same pattern for every semantic token\n},\nborderRadius: { lg: 'var(--radius)', md: 'calc(var(--radius) - 2px)',\n                sm: 'calc(var(--radius) - 4px)' }\n```\n\nDark toggle: `document.documentElement.classList.toggle('dark')`; honor\nsystem via `matchMedia('(prefers-color-scheme: dark)')` when no stored\nchoice. shadcn compat: these are the exact var names and format shadcn\nexpects; `npx shadcn@latest init` then `add button card input` works\nunchanged. Keep names and HSL format to stay compatible.\n\n## W3C DTCG token file\n\nStarter structure, `design-tokens.json`. Every leaf = `{$value, $type}`;\ntypes: color, dimension, shadow, duration. Aliases use `{layer.path.name}`.\n\n```json\n{\n  \"primitive\": {\n    \"color\": { \"blue\": { \"600\": { \"$value\": \"#2563EB\", \"$type\": \"color\" } },\n               \"gray\": { \"950\": { \"$value\": \"#030712\", \"$type\": \"color\" } } },\n    \"spacing\": { \"4\": { \"$value\": \"1rem\", \"$type\": \"dimension\" } },\n    \"duration\": { \"fast\": { \"$value\": \"150ms\", \"$type\": \"duration\" } }\n  },\n  \"semantic\": { \"color\": { \"primary\": {\n    \"$value\": \"{primitive.color.blue.600}\", \"$type\": \"color\" } } },\n  \"component\": { \"button\": { \"bg\": {\n    \"$value\": \"{semantic.color.primary}\", \"$type\": \"color\" } } },\n  \"dark\": { \"semantic\": { \"color\": { \"background\": {\n    \"$value\": \"{primitive.color.gray.950}\", \"$type\": \"color\" } } } }\n}\n```\n\n## Brand to tokens sync\n\n`docs/brand-guidelines.md` is the single source of truth (colors, typography,\nvoice, logo). Derived artifacts: `assets/design-tokens.json` and\n`assets/design-tokens.css`. Invariant: never edit guidelines alone; every\nbrand change updates all three files in one pass, then verify extraction.\n\nGenerate full 50-900 scale from each brand base hex (500 slot) via brightness\noffsets: 50 +0.9, 100 +0.8, 200 +0.6, 300 +0.4, 400 +0.2, 500 base,\n600 -0.15, 700 -0.3, 800 -0.45, 900 -0.6. Explicit light/dark hexes in the\nguidelines override the 50/100 (light) and 600 (dark) slots.\n\nBrightness offsets get muddy on saturated brand colors; prefer generating\nscales in OKLCH (fix hue/chroma, step lightness) when tooling allows.\n\n## Color rules and WCAG math\n\nRelative luminance, per channel c = value/255:\n`c_lin = c <= 0.03928 ? c/12.92 : ((c+0.055)/1.055)^2.4`\n`L = 0.2126*R + 0.7152*G + 0.0722*B`\n`ratio = (L_lighter + 0.05) / (L_darker + 0.05)`\nAA: 4.5:1 normal text, 3:1 large (18px+ or 14px bold) and UI. AAA: 7:1 / 4.5:1.\n\n60/30/10: dominant/neutral 60%, secondary 30%, accent 10% (acceptance band:\nprimary 60-70, secondary 20-30, accent 5-10). Hierarchy: primary 1-2 colors\n(CTAs, headers), secondary 2-3 (accents, interactive), neutral 3-5 (bg, text,\nborders), semantic fixed: success #22C55E, warning #F59E0B, error #EF4444,\ninfo #3B82F6. No pure #000 text (use #111827). Never meaning by color alone.\n\n## Typography system\n\nBase 16px, ratio 1.25 (Major Third).\n\n| Level | Size | Weight | Line height |\n|---|---|---|---|\n| Display | 3.815rem / 61px | 700 | 1.1 |\n| H1 | 3.052 / 49 | 700 | 1.2 |\n| H2 | 2.441 / 39 | 600 | 1.25 |\n| H3 | 1.953 / 31 | 600 | 1.3 |\n| H4 | 1.563 / 25 | 600 | 1.35 |\n| H5 | 1.25 / 20 | 600 | 1.4 |\n| Body L | 1.125 / 18 | 400 | 1.6 |\n| Body | 1 / 16 | 400 | 1.5 |\n| Small | 0.875 / 14 | 400 | 1.5 |\n| Caption | 0.75 / 12 | 400 | 1.4 |\n\nResponsive headings: h1 32px mobile to 48 desktop; h2 24 to 36; h3 20 to 28.\nTracking: display -0.02em, headings/body 0, all-caps +0.05em, small-caps\n+0.1em. Measure: 65-75ch body (`max-width: 65ch`). Weights: 400 body,\n500 buttons/nav/links, 600 subheads, 700 headings/CTAs.\n\nFont pairing: use design-search --domain typography (73 curated pairings w/\nimports + Tailwind config); design-taste governs selection taste.\n\nFloors: body 16px+, small 14+, caption 12 sparingly. No all-caps paragraphs,\nno justified text, no sub-400 weights at small sizes.\n\n## Tools\n\n- `contrast-check`: pass foreground/background hex pairs; returns ratio and\n  AA/AAA pass/fail. Run on every new pairing, in BOTH themes: text/bg, button\n  fg/bg, status colors on their surfaces.\n- `token-validate`: scan files or a directory for hardcoded hex/rgb/hsl/\n  font-family values outside `var()`. Run before shipping and as the\n  migration inventory on existing codebases.\n- `design-search --domain color \"<product type>\"`: 192 product palettes, 16\n  shadcn-style tokens each. `design-search --domain typography \"<mood>\"`: 73\n  font pairings with CSS imports and Tailwind config. Use to seed primitives\n  and pairing for a new brand before hand-tuning.\n",
+      "kind": "skill-md"
+    }
+  ]
+}