[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CSTV6P3SM3PAE28DB0RF77":3,"skill-same:01M7CSTV6P3SM3PAE28DB0RF77":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7CSTV6P3SM3PAE28DB0RF77","design-system-authoring",null,"Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns","makifbaysal\u002Ftasktrooper","makifbaysal","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F25031940?v=4","01M7CRG3ZCSYZSSEVDMW3DEYC8","Mehmet Akif Baysal","01M7CRG401FJ8YAXH5ER730XYV",122,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-system-authoring\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: design-system-authoring\ncategory: design\ndescription: Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns\n---\n# Design System Authoring\n\n## Overview\n\nA design system the team will actually build with is derived from the code that already exists, named by role, proven against contrast in both themes, and proposed — never invented in a vacuum. The proposal is what every developer run in those repositories will build with from the day it is approved, so a vague token or a missing dark value becomes a hundred one-off decisions downstream.\n\n**Core principle:** Read everything first, keep what is shared, give every deliberate difference a reason, and report the rest as drift.\n\n## 1. Find what exists\n\nRead every repository with a UI (clone the ones not in your workspace: `git clone --depth 1 \u003Croot_path or remote_url> _design\u002F\u003Cname>`, then `grep_code`\u002F`read_file` with `path: \"_design\u002F\u003Cname>\"`). Note every value with the file and line it came from.\n\n| Stack | Tokens live in | Fonts | Components |\n|---|---|---|---|\n| Web, Tailwind v4 | `@theme` in `src\u002Findex.css` \u002F `app\u002Fglobals.css`; `:root` and `.dark` \u002F `[data-theme=dark]` CSS variables | `\u003Clink>` in `index.html`, `@font-face`, `next\u002Ffont` in `app\u002Flayout.tsx` | `src\u002Fcomponents\u002F{ui,atoms,molecules,…}`, `INVENTORY.md`, `components.json`, `*.stories.tsx` |\n| Web, Tailwind v3 | `tailwind.config.{js,ts}` `theme.extend` + the CSS variables it points at | same | same |\n| Web, CSS-in-JS | `createTheme` (MUI), `extendTheme` (Chakra), `theme.ts` (styled-components \u002F emotion) | same | same |\n| iOS (SwiftUI) | `Assets.xcassets\u002F**\u002F*.colorset\u002FContents.json` (Any\u002FDark), `Theme.swift`, `Color+*.swift`, `Font+*.swift` | `UIAppFonts` in `Info.plist` | `Views\u002FComponents\u002F`, `DesignSystem\u002F` |\n| Android (Compose) | `ui\u002Ftheme\u002FColor.kt`, `Theme.kt`, `Type.kt`, `Shape.kt` | `res\u002Ffont\u002F` | `ui\u002Fcomponents\u002F` |\n| Android (views) | `res\u002Fvalues\u002Fcolors.xml`, `themes.xml`, `values-night\u002F`, `dimens.xml` | `res\u002Ffont\u002F` | `res\u002Flayout\u002F`, custom views |\n| Flutter | `ThemeData`, `ColorScheme`, `ThemeExtension`s (`lib\u002Fui\u002Fcore\u002Ftheme\u002F`) | `fonts:` in `pubspec.yaml` | `lib\u002Fui\u002Fcore\u002F{atoms,molecules,organisms}` |\n\nFind the real palette by frequency, not by the theme file alone — a value used in 40 places is the palette, one used once is a one-off or drift. Read-only, in the workspace:\n\n```\ngrep -rhoE '#[0-9a-fA-F]{6}\\b' src | tr 'a-f' 'A-F' | sort | uniq -c | sort -rn | head -40\ngrep -rhoE 'Color\\(0x[0-9A-Fa-f]{8}\\)' lib | sort | uniq -c | sort -rn | head -40\n```\n\n### Nothing to derive from\n\nA new product with no UI code yet: the brief is the source. Ground every choice in the audience, the subject matter and the references the brief names (rule avoid-ai-default-looks applies hardest here), make ONE deliberate proposal rather than a menu, and write each decision with its reason in DESIGN.md's Overview — the human approves or annotates it like any other.\n\n## 2. Name by role, never by hue\n\n- **Colour:** `background`, `foreground`, `surface`, `surface-raised`, `muted`, `muted-foreground`, `border`, `input`, `ring`, and each action\u002Fstatus colour with its text-on-it pair: `primary`\u002F`on-primary`, `secondary`\u002F`on-secondary`, `accent`\u002F`on-accent`, `destructive`\u002F`on-destructive`, `success`, `warning`, `info` (each with `on-*`). Keep the convention the code already uses (`primary-foreground` in a shadcn repo) — one convention per design system.\n- **Type:** `font.family.sans` \u002F `font.family.display` \u002F `font.family.mono`, a `font.size` scale, `font.weight`, `line-height`, and the named roles (`typography.heading-1`, `body`, `body-sm`, `label`, `caption`) as composite tokens.\n- **Spacing** on a 4px base (`space.1` = 4px … `space.16` = 64px); **radius** (`radius.sm\u002Fmd\u002Flg\u002Ffull`); **shadow** by elevation (`shadow.sm\u002Fmd\u002Flg`); **motion** (`duration.fast\u002Fnormal`, `easing.standard`); **layout** (`breakpoint.sm\u002Fmd\u002Flg\u002Fxl`, `container.max`); on mobile `size.touch-target`.\n- `blue-500` is a palette value, not a role. A raw palette may exist as its own `palette` group that role tokens alias (`\"$value\": \"{palette.green.700}\"`); components only ever see roles.\n\n## 3. The DTCG token tree\n\nGroups are objects; a token is an object with `$value` (and `$type`, on the token or inherited from its group; `$description` where the use is not obvious). Values in the form the code writes them — `#RRGGBB` hex by default (the contrast check reads it), `16px`, `150ms`. Both themes carry the SAME keys; a key missing from one theme is a defect.\n\n```json\n{\n  \"color\": {\n    \"$type\": \"color\",\n    \"light\": {\n      \"background\": { \"$value\": \"#FFFFFF\" },\n      \"foreground\": { \"$value\": \"#1C2024\" },\n      \"muted-foreground\": { \"$value\": \"#5A6560\" },\n      \"primary\": { \"$value\": \"#1F5F4A\", \"$description\": \"Primary action, links, focus ring\" },\n      \"on-primary\": { \"$value\": \"#FFFFFF\" }\n    },\n    \"dark\": {\n      \"background\": { \"$value\": \"#111416\" },\n      \"foreground\": { \"$value\": \"#E8ECEA\" },\n      \"muted-foreground\": { \"$value\": \"#9AA5A0\" },\n      \"primary\": { \"$value\": \"#5FB894\" },\n      \"on-primary\": { \"$value\": \"#0B1F17\" }\n    }\n  },\n  \"font\": {\n    \"family\": { \"sans\": { \"$type\": \"fontFamily\", \"$value\": [\"Source Sans 3\", \"system-ui\", \"sans-serif\"] } },\n    \"size\": { \"$type\": \"dimension\", \"body\": { \"$value\": \"16px\" }, \"heading-1\": { \"$value\": \"32px\" } }\n  },\n  \"space\": { \"$type\": \"dimension\", \"1\": { \"$value\": \"4px\" }, \"2\": { \"$value\": \"8px\" }, \"4\": { \"$value\": \"16px\" } },\n  \"radius\": { \"$type\": \"dimension\", \"md\": { \"$value\": \"6px\" } },\n  \"duration\": { \"$type\": \"duration\", \"fast\": { \"$value\": \"150ms\" } }\n}\n```\n\nA repository layer holds ONLY the tokens it adds or overrides — a layer token replaces the base token whole; a group merges key by key. Never `null` (refused: a layer cannot delete a base token), never a copy of the base.\n\n## 4. Base, layer or drift\n\n| The difference | It is | It goes |\n|---|---|---|\n| Every UI repository does it | base | the project base |\n| One repository differs on purpose, for a reason a user or a platform gives — a marketing site's campaign colours, iOS 44pt \u002F Android 48dp touch targets, a TV app's larger type | layer | that repository's layer, with the reason in `rationale` |\n| One repository differs because a value was copied and changed — `#1F5F4A` vs `#1F5F4B`, 15px body vs 16px, a fourth grey | drift | the report's drift table; the Apply task after approval fixes it |\n| The code differs from an already-approved design system | drift | same |\n\nWhen unsure, it is drift — a layer needs a reason you can write in one sentence. A repository with no project base gets a layer-only, complete design system (every token, DESIGN.md, inventory). If the repository belongs to several projects and none is chosen as its base, ask with `record_open_questions` before proposing anything.\n\nProposing: base first (`scope: \"project\"`, `project_id`, `design_md`, `tokens`, `inventory_md`), then each layer (`scope: \"repository\"`, `repository_id`, `tokens`, `rationale`). Calling it again for the same target from the same task replaces that pending version — that is how you revise. The human approves every version at once by approving the task.\n\n### Lint, after every proposal\n\nEvery `propose_design_system` result carries `lint`, and every version `get_design_system` returns carries it too:\n\n| Code | Severity | Means | Fix |\n|---|---|---|---|\n| `unresolved_alias` | error | `{palette.green.700}` names a token that does not exist | point it at a real token, or add that token |\n| `invalid_color` | error | a colour value that is not hex, `rgb()`, `hsl()`, `oklch()`, `oklab()` or a DTCG colour object | write it as `#RRGGBB`, the form the code uses |\n| `contrast_below_aa` | error | a colour and its `-foreground` \u002F `on-` pair below 4.5:1, with the `ratio` | change the token until the pair passes — never footnote it |\n| `empty_group` | warning | a group with no tokens in it | fill it or drop it |\n| `missing_section` | warning | a DESIGN.md section the base lacks | write the section (§5) |\n\nFix every `error` and propose again before the report is attached — a version with an error finding never goes to review. A `warning` you leave on purpose is named in the report with its reason.\n\n## 5. DESIGN.md — this order, these headings\n\n1. **Overview** — the product, its audience, the feel in three adjectives, and the deliberate choices that make it this product's look and not a template's. The context block other agents get shows only the opening of DESIGN.md, so the first paragraph carries the rules that matter most.\n2. **Colors** — each role, what it is for, both themes, the contrast pairs.\n3. **Typography** — families and why, the scale (size \u002F line-height \u002F weight per role), measure.\n4. **Layout** — breakpoints, grid, container widths, the spacing scale and rhythm, density.\n5. **Elevation & Depth** — shadow levels and when each is used; borders vs shadows.\n6. **Shapes** — the radius scale and where each applies; the icon library, stroke and sizes.\n7. **Components** — the core set, their variants and states; points at the inventory.\n8. **Do's and Don'ts** — concrete and checkable (\"One primary button per view.\" \"Never a raw hex in a component.\" \"Status is never colour alone.\").\n\nPlain markdown, under ~8 KB. A layer's `design_md` covers only what the layer changes and why.\n\n## 6. Component inventory\n\nOne line per component, grouped by level, with where it lives in each repository:\n\n```\natom · Button · actions · primary\u002Fsecondary\u002Fghost\u002Fdestructive × sm\u002Fmd\u002Flg · default\u002Fhover\u002Ffocus\u002Factive\u002Fdisabled\u002Floading · web: src\u002Fcomponents\u002Fatoms\u002FButton.tsx · ios: Views\u002FComponents\u002FAppButton.swift\nmolecule · SearchField · filter a list · with\u002Fwithout clear · default\u002Ffocus\u002Ffilled\u002Fdisabled · web: src\u002Fcomponents\u002Fmolecules\u002FSearchField.tsx · ios: — (missing)\n```\n\nA component one repository lacks is listed with `— (missing)`; two implementations of the same thing in one repository are drift.\n\n## 7. Contrast check (WCAG 2.x AA), both themes\n\nBody text ≥ 4.5:1; large text (≥ 24px, or ≥ 18.66px bold) and UI boundaries, icons and focus rings ≥ 3:1. Check every `on-*` against its colour, `foreground` and `muted-foreground` against `background` and `surface`, `primary` as link text on `background`, `ring` against `background`. Read-only, nothing written:\n\n```\npython3 - \u003C\u003C'PY'\ndef lum(h):\n    h = h.lstrip('#')\n    c = [int(h[i:i + 2], 16) \u002F 255 for i in (0, 2, 4)]\n    c = [x \u002F 12.92 if x \u003C= 0.04045 else ((x + 0.055) \u002F 1.055) ** 2.4 for x in c]\n    return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]\ndef ratio(a, b):\n    hi, lo = sorted((lum(a), lum(b)), reverse=True)\n    return (hi + 0.05) \u002F (lo + 0.05)\nfor name, fg, bg in [\n    (\"light foreground\u002Fbackground\", \"#1C2024\", \"#FFFFFF\"),\n    (\"light muted-foreground\u002Fbackground\", \"#5A6560\", \"#FFFFFF\"),\n    (\"dark on-primary\u002Fprimary\", \"#0B1F17\", \"#5FB894\"),\n]:\n    r = ratio(fg, bg)\n    print(f\"{name}: {r:.2f} {'AA' if r >= 4.5 else 'large text only' if r >= 3 else 'FAIL'}\")\nPY\n```\n\nConvert OKLCH\u002FHSL values to hex first. A failing pair is fixed in the token, never footnoted. The server's lint checks each colour against its `-foreground` \u002F `on-` pair; this check covers the rest — muted text, links, the focus ring. The ratio table goes into the report.\n\n## 8. The report\n\nONE self-contained HTML document (sanitizer-safe-html), titled `design system: \u003Cproject or repository> v\u003CN>`: swatches for both themes (each with its token name, value, a text sample in its `on-*` colour and the ratio); the type scale set in real copy; spacing, radius and elevation samples; the core components drawn in their states; per repository a table — token · today in the repository (file:line) · design system · layer or drift; and the lint warnings left, each with its reason. It is what the human approves; everything a reviewer may question is text, not only a picture. Serve it on loopback (screen-mockup-html's self-check) and save a full-page `browser_screenshot` with `attach_to_task: true` and `title: \"design-system-\u003Cname>-v\u003CN>\"`, so the human sees the palette on the task.\n\n## Worked Example\n\n```\nweb (Tailwind v4): --primary #1F5F4A (src\u002Findex.css:14), body 16px, buttons 40px tall\nios (SwiftUI):     Primary.colorset #1F5F4B, body .body (17pt), buttons 44pt tall\n\n#1F5F4A vs #1F5F4B → drift (one digit, no reason) → base color.light.primary #1F5F4A; drift row for ios\n17pt vs 16px body  → layer for ios: font.size.body 17px, rationale \"iOS Dynamic Type default body size\"\n44pt vs 40px       → layer for ios: size.touch-target 44px, rationale \"Apple HIG minimum hit target\"\n```\n\n## Common Mistakes\n\n- Inventing a palette for a product whose repositories already have one.\n- Hue names (`green-700`) where a role belongs.\n- A dark theme with fewer keys than the light one.\n- A layer that restates the whole base, or encodes drift with an invented reason.\n- Proposing without having run the contrast check.\n- Attaching the report while the last `propose_design_system` result still lists an `error`.\n\n## Red Flags\n\n- A token value you cannot trace to a file, the brief, or a decision written in the notes.\n- `rationale` that describes the value instead of the reason (\"uses a darker green\").\n- A report with swatches but no per-repository layer\u002Fdrift table.\n","# Design System Authoring\n\n## Overview\n\nA design system the team will actually build with is derived from the code that already exists, named by role, proven against contrast in both themes, and proposed — never invented in a vacuum. The proposal is what every developer run in those repositories will build with from the day it is approved, so a vague token or a missing dark value becomes a hundred one-off decisions downstream.\n\n**Core principle:** Read everything first, keep what is shared, give every deliberate difference a reason, and report the rest as drift.\n\n## 1. Find what exists\n\nRead every repository with a UI (clone the ones not in your workspace: `git clone --depth 1 \u003Croot_path or remote_url> _design\u002F\u003Cname>`, then `grep_code`\u002F`read_file` with `path: \"_design\u002F\u003Cname>\"`). Note every value with the file and line it came from.\n\n| Stack | Tokens live in | Fonts | Components |\n|---|---|---|---|\n| Web, Tailwind v4 | `@theme` in `src\u002Findex.css` \u002F `app\u002Fglobals.css`; `:root` and `.dark` \u002F `[data-theme=dark]` CSS variables | `\u003Clink>` in `index.html`, `@font-face`, `next\u002Ffont` in `app\u002Flayout.tsx` | `src\u002Fcomponents\u002F{ui,atoms,molecules,…}`, `INVENTORY.md`, `components.json`, `*.stories.tsx` |\n| Web, Tailwind v3 | `tailwind.config.{js,ts}` `theme.extend` + the CSS variables it points at | same | same |\n| Web, CSS-in-JS | `createTheme` (MUI), `extendTheme` (Chakra), `theme.ts` (styled-components \u002F emotion) | same | same |\n| iOS (SwiftUI) | `Assets.xcassets\u002F**\u002F*.colorset\u002FContents.json` (Any\u002FDark), `Theme.swift`, `Color+*.swift`, `Font+*.swift` | `UIAppFonts` in `Info.plist` | `Views\u002FComponents\u002F`, `DesignSystem\u002F` |\n| Android (Compose) | `ui\u002Ftheme\u002FColor.kt`, `Theme.kt`, `Type.kt`, `Shape.kt` | `res\u002Ffont\u002F` | `ui\u002Fcomponents\u002F` |\n| Android (views) | `res\u002Fvalues\u002Fcolors.xml`, `themes.xml`, `values-night\u002F`, `dimens.xml` | `res\u002Ffont\u002F` | `res\u002Flayout\u002F`, custom views |\n| Flutter | `ThemeData`, `ColorScheme`, `ThemeExtension`s (`lib\u002Fui\u002Fcore\u002Ftheme\u002F`) | `fonts:` in `pubspec.yaml` | `lib\u002Fui\u002Fcore\u002F{atoms,molecules,organisms}` |\n\nFind the real palette by frequency, not by the theme file alone — a value used in 40 places is the palette, one used once is a one-off or drift. Read-only, in the workspace:\n\n```\ngrep -rhoE '#[0-9a-fA-F]{6}\\b' src | tr 'a-f' 'A-F' | sort | uniq -c | sort -rn | head -40\ngrep -rhoE 'Color\\(0x[0-9A-Fa-f]{8}\\)' lib | sort | uniq -c | sort -rn | head -40\n```\n\n### Nothing to derive from\n\nA new product with no UI code yet: the brief is the source. Ground every choice in the audience, the subject matter and the references the brief names (rule avoid-ai-default-looks applies hardest here), make ONE deliberate proposal rather than a menu, and write each decision with its reason in DESIGN.md's Overview — the human approves or annotates it like any other.\n\n## 2. Name by role, never by hue\n\n- **Colour:** `background`, `foreground`, `surface`, `surface-raised`, `muted`, `muted-foreground`, `border`, `input`, `ring`, and each action\u002Fstatus colour with its text-on-it pair: `primary`\u002F`on-primary`, `secondary`\u002F`on-secondary`, `accent`\u002F`on-accent`, `destructive`\u002F`on-destructive`, `success`, `warning`, `info` (each with `on-*`). Keep the convention the code already uses (`primary-foreground` in a shadcn repo) — one convention per design system.\n- **Type:** `font.family.sans` \u002F `font.family.display` \u002F `font.family.mono`, a `font.size` scale, `font.weight`, `line-height`, and the named roles (`typography.heading-1`, `body`, `body-sm`, `label`, `caption`) as composite tokens.\n- **Spacing** on a 4px base (`space.1` = 4px … `space.16` = 64px); **radius** (`radius.sm\u002Fmd\u002Flg\u002Ffull`); **shadow** by elevation (`shadow.sm\u002Fmd\u002Flg`); **motion** (`duration.fast\u002Fnormal`, `easing.standard`); **layout** (`breakpoint.sm\u002Fmd\u002Flg\u002Fxl`, `container.max`); on mobile `size.touch-target`.\n- `blue-500` is a palette value, not a role. A raw palette may exist as its own `palette` group that role tokens alias (`\"$value\": \"{palette.green.700}\"`); components only ever see roles.\n\n## 3. The DTCG token tree\n\nGroups are objects; a token is an object with `$value` (and `$type`, on the token or inherited from its group; `$description` where the use is not obvious). Values in the form the code writes them — `#RRGGBB` hex by default (the contrast check reads it), `16px`, `150ms`. Both themes carry the SAME keys; a key missing from one theme is a defect.\n\n```json\n{\n  \"color\": {\n    \"$type\": \"color\",\n    \"light\": {\n      \"background\": { \"$value\": \"#FFFFFF\" },\n      \"foreground\": { \"$value\": \"#1C2024\" },\n      \"muted-foreground\": { \"$value\": \"#5A6560\" },\n      \"primary\": { \"$value\": \"#1F5F4A\", \"$description\": \"Primary action, links, focus ring\" },\n      \"on-primary\": { \"$value\": \"#FFFFFF\" }\n    },\n    \"dark\": {\n      \"background\": { \"$value\": \"#111416\" },\n      \"foreground\": { \"$value\": \"#E8ECEA\" },\n      \"muted-foreground\": { \"$value\": \"#9AA5A0\" },\n      \"primary\": { \"$value\": \"#5FB894\" },\n      \"on-primary\": { \"$value\": \"#0B1F17\" }\n    }\n  },\n  \"font\": {\n    \"family\": { \"sans\": { \"$type\": \"fontFamily\", \"$value\": [\"Source Sans 3\", \"system-ui\", \"sans-serif\"] } },\n    \"size\": { \"$type\": \"dimension\", \"body\": { \"$value\": \"16px\" }, \"heading-1\": { \"$value\": \"32px\" } }\n  },\n  \"space\": { \"$type\": \"dimension\", \"1\": { \"$value\": \"4px\" }, \"2\": { \"$value\": \"8px\" }, \"4\": { \"$value\": \"16px\" } },\n  \"radius\": { \"$type\": \"dimension\", \"md\": { \"$value\": \"6px\" } },\n  \"duration\": { \"$type\": \"duration\", \"fast\": { \"$value\": \"150ms\" } }\n}\n```\n\nA repository layer holds ONLY the tokens it adds or overrides — a layer token replaces the base token whole; a group merges key by key. Never `null` (refused: a layer cannot delete a base token), never a copy of the base.\n\n## 4. Base, layer or drift\n\n| The difference | It is | It goes |\n|---|---|---|\n| Every UI repository does it | base | the project base |\n| One repository differs on purpose, for a reason a user or a platform gives — a marketing site's campaign colours, iOS 44pt \u002F Android 48dp touch targets, a TV app's larger type | layer | that repository's layer, with the reason in `rationale` |\n| One repository differs because a value was copied and changed — `#1F5F4A` vs `#1F5F4B`, 15px body vs 16px, a fourth grey | drift | the report's drift table; the Apply task after approval fixes it |\n| The code differs from an already-approved design system | drift | same |\n\nWhen unsure, it is drift — a layer needs a reason you can write in one sentence. A repository with no project base gets a layer-only, complete design system (every token, DESIGN.md, inventory). If the repository belongs to several projects and none is chosen as its base, ask with `record_open_questions` before proposing anything.\n\nProposing: base first (`scope: \"project\"`, `project_id`, `design_md`, `tokens`, `inventory_md`), then each layer (`scope: \"repository\"`, `repository_id`, `tokens`, `rationale`). Calling it again for the same target from the same task replaces that pending version — that is how you revise. The human approves every version at once by approving the task.\n\n### Lint, after every proposal\n\nEvery `propose_design_system` result carries `lint`, and every version `get_design_system` returns carries it too:\n\n| Code | Severity | Means | Fix |\n|---|---|---|---|\n| `unresolved_alias` | error | `{palette.green.700}` names a token that does not exist | point it at a real token, or add that token |\n| `invalid_color` | error | a colour value that is not hex, `rgb()`, `hsl()`, `oklch()`, `oklab()` or a DTCG colour object | write it as `#RRGGBB`, the form the code uses |\n| `contrast_below_aa` | error | a colour and its `-foreground` \u002F `on-` pair below 4.5:1, with the `ratio` | change the token until the pair passes — never footnote it |\n| `empty_group` | warning | a group with no tokens in it | fill it or drop it |\n| `missing_section` | warning | a DESIGN.md section the base lacks | write the section (§5) |\n\nFix every `error` and propose again before the report is attached — a version with an error finding never goes to review. A `warning` you leave on purpose is named in the report with its reason.\n\n## 5. DESIGN.md — this order, these headings\n\n1. **Overview** — the product, its audience, the feel in three adjectives, and the deliberate choices that make it this product's look and not a template's. The context block other agents get shows only the opening of DESIGN.md, so the first paragraph carries the rules that matter most.\n2. **Colors** — each role, what it is for, both themes, the contrast pairs.\n3. **Typography** — families and why, the scale (size \u002F line-height \u002F weight per role), measure.\n4. **Layout** — breakpoints, grid, container widths, the spacing scale and rhythm, density.\n5. **Elevation & Depth** — shadow levels and when each is used; borders vs shadows.\n6. **Shapes** — the radius scale and where each applies; the icon library, stroke and sizes.\n7. **Components** — the core set, their variants and states; points at the inventory.\n8. **Do's and Don'ts** — concrete and checkable (\"One primary button per view.\" \"Never a raw hex in a component.\" \"Status is never colour alone.\").\n\nPlain markdown, under ~8 KB. A layer's `design_md` covers only what the layer changes and why.\n\n## 6. Component inventory\n\nOne line per component, grouped by level, with where it lives in each repository:\n\n```\natom · Button · actions · primary\u002Fsecondary\u002Fghost\u002Fdestructive × sm\u002Fmd\u002Flg · default\u002Fhover\u002Ffocus\u002Factive\u002Fdisabled\u002Floading · web: src\u002Fcomponents\u002Fatoms\u002FButton.tsx · ios: Views\u002FComponents\u002FAppButton.swift\nmolecule · SearchField · filter a list · with\u002Fwithout clear · default\u002Ffocus\u002Ffilled\u002Fdisabled · web: src\u002Fcomponents\u002Fmolecules\u002FSearchField.tsx · ios: — (missing)\n```\n\nA component one repository lacks is listed with `— (missing)`; two implementations of the same thing in one repository are drift.\n\n## 7. Contrast check (WCAG 2.x AA), both themes\n\nBody text ≥ 4.5:1; large text (≥ 24px, or ≥ 18.66px bold) and UI boundaries, icons and focus rings ≥ 3:1. Check every `on-*` against its colour, `foreground` and `muted-foreground` against `background` and `surface`, `primary` as link text on `background`, `ring` against `background`. Read-only, nothing written:\n\n```\npython3 - \u003C\u003C'PY'\ndef lum(h):\n    h = h.lstrip('#')\n    c = [int(h[i:i + 2], 16) \u002F 255 for i in (0, 2, 4)]\n    c = [x \u002F 12.92 if x \u003C= 0.04045 else ((x + 0.055) \u002F 1.055) ** 2.4 for x in c]\n    return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]\ndef ratio(a, b):\n    hi, lo = sorted((lum(a), lum(b)), reverse=True)\n    return (hi + 0.05) \u002F (lo + 0.05)\nfor name, fg, bg in [\n    (\"light foreground\u002Fbackground\", \"#1C2024\", \"#FFFFFF\"),\n    (\"light muted-foreground\u002Fbackground\", \"#5A6560\", \"#FFFFFF\"),\n    (\"dark on-primary\u002Fprimary\", \"#0B1F17\", \"#5FB894\"),\n]:\n    r = ratio(fg, bg)\n    print(f\"{name}: {r:.2f} {'AA' if r >= 4.5 else 'large text only' if r >= 3 else 'FAIL'}\")\nPY\n```\n\nConvert OKLCH\u002FHSL values to hex first. A failing pair is fixed in the token, never footnoted. The server's lint checks each colour against its `-foreground` \u002F `on-` pair; this check covers the rest — muted text, links, the focus ring. The ratio table goes into the report.\n\n## 8. The report\n\nONE self-contained HTML document (sanitizer-safe-html), titled `design system: \u003Cproject or repository> v\u003CN>`: swatches for both themes (each with its token name, value, a text sample in its `on-*` colour and the ratio); the type scale set in real copy; spacing, radius and elevation samples; the core components drawn in their states; per repository a table — token · today in the repository (file:line) · design system · layer or drift; and the lint warnings left, each with its reason. It is what the human approves; everything a reviewer may question is text, not only a picture. Serve it on loopback (screen-mockup-html's self-check) and save a full-page `browser_screenshot` with `attach_to_task: true` and `title: \"design-system-\u003Cname>-v\u003CN>\"`, so the human sees the palette on the task.\n\n## Worked Example\n\n```\nweb (Tailwind v4): --primary #1F5F4A (src\u002Findex.css:14), body 16px, buttons 40px tall\nios (SwiftUI):     Primary.colorset #1F5F4B, body .body (17pt), buttons 44pt tall\n\n#1F5F4A vs #1F5F4B → drift (one digit, no reason) → base color.light.primary #1F5F4A; drift row for ios\n17pt vs 16px body  → layer for ios: font.size.body 17px, rationale \"iOS Dynamic Type default body size\"\n44pt vs 40px       → layer for ios: size.touch-target 44px, rationale \"Apple HIG minimum hit target\"\n```\n\n## Common Mistakes\n\n- Inventing a palette for a product whose repositories already have one.\n- Hue names (`green-700`) where a role belongs.\n- A dark theme with fewer keys than the light one.\n- A layer that restates the whole base, or encodes drift with an invented reason.\n- Proposing without having run the contrast check.\n- Attaching the report while the last `propose_design_system` result still lists an `error`.\n\n## Red Flags\n\n- A token value you cannot trace to a file, the brief, or a decision written in the notes.\n- `rationale` that describes the value instead of the reason (\"uses a darker green\").\n- A report with swatches but no per-repository layer\u002Fdrift table.\n",{"name":5,"category":24,"description":7},"design","main","910394a0b6db9fc8c9a8f36328ec421d3ebd8b38","catalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-system-authoring",18,"https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper","https:\u002F\u002Ftasktrooper.ai","https:\u002F\u002Fgithub.com\u002Fmakifbaysal","Senior Software Developer","2026-11-15 04:50:29",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add makifbaysal\u002Ftasktrooper --skill design-system-authoring",{"tool":40,"command":41},"bunx","bunx skills add makifbaysal\u002Ftasktrooper --skill design-system-authoring",{"tool":43,"command":44},"pnpm","pnpm dlx skills add makifbaysal\u002Ftasktrooper --skill design-system-authoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-system-authoring\u002FSKILL.md",true,[],[49,55,62,69,76,83],{"skillNo":50,"name":51,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7CSVEPQW6J6TD6CS2T5FPNZ","visual-craft","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fvisual-craft\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7CSVAQG91ETHQ0HBNZDG5FR","ux-copy","Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fux-copy\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7CSV6H0J38659NDXHJQ8396","screen-mockup-html","Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fscreen-mockup-html\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CSV3JFRF3BM3XK52M7YEYR","performance-awareness","How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fperformance-awareness\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7CSTZDH00YRF5SCT7BRT9QD","design-variants","Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-variants\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7CSTQDQYWEECNZFFD8RTF4P","design-review","Use when a design task asks you to compare a built screen with its approved design - screenshots at 1440, 768 and 375 attached to the task, Blocker\u002FHigh\u002FMedium\u002FNitpick triage, evidence per finding, problems not prescriptions","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-review\u002FSKILL.md",[],[]]