[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7B47BVP5GKP46GS29VYF7NB":3,"skill-same:01M7B47BVP5GKP46GS29VYF7NB":52},{"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":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7B47BVP5GKP46GS29VYF7NB","ds-theme",null,"Use when the look of this project's design system is to change: a colour, a font, a weight, corners, elevation, motion or dark mode, anything in DESIGN.md or the theme folder, and when the Material 3 (MD3) kit in the ds folder is updated. Writes the project's DESIGN.md from a brief, generates the theme from it, reads the warnings, wires the entry CSS, and takes a kit update without losing the theme.","emyann\u002Fnemia","emyann","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F4748419?v=4","01M7B458J23KJ5S5AEBR86G7RN","Yann RENAUDIN","01M7B458JPM0CCBDP4KCR6NATT",3,"MIT","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fapps\u002Fweb\u002F.claude\u002Fskills\u002Fds-theme\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: ds-theme\ndescription: \"Use when the look of this project's design system is to change: a colour, a font, a weight, corners, elevation, motion or dark mode, anything in DESIGN.md or the theme folder, and when the Material 3 (MD3) kit in the ds folder is updated. Writes the project's DESIGN.md from a brief, generates the theme from it, reads the warnings, wires the entry CSS, and takes a kit update without losing the theme.\"\n---\n\n# ds-theme: the project's look comes from its DESIGN.md\n\nThe project decides its look in one file, `DESIGN.md` at its root. The kit's\ngenerator turns that file into the theme the components read. Nobody edits a\ngenerated file: the next generation writes it again. And a look is not what\na kit file is edited for: that edit is allowed but priced (the `ds-build`\nskill, \"What a project may change\"), and `DESIGN.md` reaches the look for\nfree.\n\n`\u003Ckit>` below is the kit's folder in this project: the `ds` folder under the\n`ui` alias of `components.json` (`src\u002Fcomponents\u002Fui\u002Fds` in most projects).\nFind it once, then read every `\u003Ckit>\u002F…` path with it.\n\n| File                              | Whose   | What it is                                                                 |\n| :-------------------------------- | :------ | :------------------------------------------------------------------------- |\n| `DESIGN.md`                       | project | The look, as decided. The only file edited                                 |\n| `theme\u002Ftheme.css`                 | project | Generated: the 49 colour roles in both schemes, the font hooks             |\n| `theme\u002Ftheme.v4.css`              | project | Generated: the Tailwind mapping with the project's type, corners, motion   |\n| `theme\u002FDESIGN.resolved.md`        | project | Generated: the complete DESIGN.md, every value filled in. Read it, never edit it |\n| `\u003Ckit>\u002FDESIGN.md`                 | kit     | The kit's neutral default, the starting file. Copied, not changed: an update rewrites it |\n| `\u003Ckit>\u002Ftokens\u002Ftheme.css`          | kit     | The default theme, what the project shows until it generates its own       |\n| `\u003Ckit>\u002Ftokens\u002Ftheme.v4.css`       | kit     | The default mapping, and the template the generator writes the project's from |\n| `\u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs` | kit     | The generator's command                                                    |\n| `\u003Ckit>\u002Ftokens\u002Fdesign-md.mjs`      | kit     | The derivation it runs                                                     |\n\nWhat every name in a DESIGN.md means to the kit, what is ignored and what is\nrefused is in `design-md.md`, beside this file\n(`.claude\u002Fskills\u002Fds-theme\u002Fdesign-md.md`). Read it before writing a role, a\ntype value or the reference block.\n\nIf `\u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs` is missing, the whole kit was not\ninstalled: run `npx shadcn add @ds\u002Fds` first.\n\n## 1. Start from a file\n\nIf the project has no `DESIGN.md` at its root, copy the kit's:\n\n```bash\ncp \u003Ckit>\u002FDESIGN.md DESIGN.md\n```\n\nIf it has one, keep it: it is the project's decision. Never overwrite it with\nthe kit's, and never write the project's look into `\u003Ckit>\u002FDESIGN.md`, which an\nupdate replaces.\n\n## 2. Write the brief into it\n\nTurn the brief into tokens in the front matter, and say why in the prose. The\nprose is for people and for the next agent; the generator reads only the front\nmatter and one CSS block.\n\n- **`name`, `description`**: the project's, not the kit's.\n- **`scheme`**: `light` or `dark`, the scheme the written colours belong to. A\n  brief that is dark by nature (cyberpunk, a terminal, a cinema) writes\n  `scheme: dark`; the light scheme is then derived from the keys. Always\n  write it: with none, the generator reads it from the file's ground and\n  lists that as assumed.\n- **`colors`**: write `seed`: with none, the generator reads it from\n  `primary` and lists that as assumed. Add `primary-key`, `secondary-key`,\n  `tertiary-key` for the brief's main colours, `neutral-key` to tint the\n  surfaces. Then write a role (`primary`, `surface`, `on-surface`, …) only\n  where an exact colour matters: a written role holds in the written scheme\n  only, a key holds in both.\n- **`typography`**: at least `fontFamily` on `display-large` and\n  `body-large`. The first is the brand face (display, headline, title), the\n  second the plain face (body, label), and a role that writes no family keeps\n  its face's. A role that writes another family takes it (labels in a squared\n  face under running text in a reading face): each family is one more font\n  the project loads. No `typography` at all means Roboto.\n- **`rounded`**: the six corners. Sharp looks lower them all; `full` stays a\n  pill unless the brief wants square buttons.\n- **`## Reference CSS`** in the body: elevation (a glow instead of a shadow, a\n  hairline, `none`), state layer opacities, easings, durations, and\n  `--md3-dark-mode: class` or `system`.\n- **The prose**: replace the kit's sections with the project's own (Overview,\n  Colors, Typography, and whatever the brief needs). Remove what speaks of the\n  kit's default.\n\nA DESIGN.md that arrives from elsewhere, or a brief with colour names of its\nown, is mapped by you onto `seed`, the keys and the 49 roles: see \"Colour\nnames that are not the kit's\" in `design-md.md`. The other names may stay in\nthe file. They are ignored and listed as warnings. A file in the format's own\nwords (no `scheme`, no `seed`, sizes written `title-md` and `rounded.sm`)\ngenerates as it is, with what was assumed listed: take that as a first\ndrawing, then write `scheme` and `seed` into the file.\n\n## 3. Generate\n\n```bash\nnpx tsx \u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs DESIGN.md --out theme\n```\n\nIt writes `theme\u002Ftheme.css`, `theme\u002Ftheme.v4.css` and\n`theme\u002FDESIGN.resolved.md`, and prints one line naming them with the number of\nwarnings. Record the command once in the project's `package.json`, with the\nreal path in place of `\u003Ckit>`:\n\n```json\n{ \"scripts\": { \"theme:generate\": \"tsx \u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs DESIGN.md --out theme\" } }\n```\n\nNever pass `--out \u003Ckit>\u002Ftokens`: those are the kit's files and an update\nwrites over them.\n\n## 4. Read the warnings\n\nEach `warning:` line on stderr is something the file says that is not in the\ntheme, or a pair that reads badly. They are also in `## Generator warnings`\nat the end of `theme\u002FDESIGN.resolved.md`. For each one, decide:\n\n- **an unknown name** (`colors.brand-pink`, `typography.h1`, `rounded.pill`):\n  map it to a name the kit reads, or leave it and say it is ignored;\n- **assumed** (`scheme`, `colors.seed`): the file wrote none and the kit read\n  it from the token the line names. Write the key into DESIGN.md, the value\n  the line gives or the one the brief means;\n- **a value with no variable** (a tracking on a role Material gives none):\n  not applied; drop it or accept it. A weight is applied on every role;\n- **poor contrast**: a written role under 4.5:1 against its pair. Fix the\n  role or write its partner. Do not leave it;\n- **the reference block was not read**: fix the heading, the `css` fence or\n  the `:root` selector.\n\nExit code 1 with nothing written means the file was refused: no front matter,\nno `scheme` and no `background` or `surface` to read one from, no `seed` and\nno `primary`, a colour that is not a hex, or a type value, a\ncorner, a family or a reference value that is not one value of its kind (a\nsize with no unit, an easing written as a `var()`). The message names the\ntoken and says what to write.\n\nThen lint both files with the format's own linter:\n\n```bash\nnpx designmd lint DESIGN.md\nnpx designmd lint theme\u002FDESIGN.resolved.md\n```\n\nBoth must end with `\"errors\": 0`. The linter's `missing-primary` warning on\n`DESIGN.md` only says the file writes keys and no `primary` role: the kit\nderives it, and the resolved file has it.\n\n## 5. Point the entry CSS at the theme\n\nThe whole install writes nothing into the entry CSS, at a first install or\nat an update: the theme is whatever that file imports. Replace the kit's two theme imports with the project's (paths\nare relative to the entry CSS; here it is `src\u002Findex.css`):\n\n```css\n@import \"tailwindcss\";\n@import \"..\u002Ftheme\u002Ftheme.css\";\n@import \"..\u002Ftheme\u002Ftheme.v4.css\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:where(.dark, .dark *));\n```\n\n- Before a theme of its own, the same two lines import\n  `\u003Ckit>\u002Ftokens\u002Ftheme.css` and `\u003Ckit>\u002Ftokens\u002Ftheme.v4.css`. Import one pair,\n  never both.\n- Every `@import` stays above any other at-rule. Vite drops an `@import` that\n  comes after `@custom-variant` or `@source`, silently.\n- With `--md3-dark-mode: class` hold one `@custom-variant dark` line, exactly\n  as above, and switch by putting `dark` on `\u003Chtml>`. A project initialised\n  by shadcn has `@custom-variant dark (&:is(.dark *));`, which misses the\n  element that carries the class: replace it. With `system`, remove the line\n  altogether: Tailwind's `dark:` then follows the system setting, as the\n  theme does.\n- If the project has stock shadcn components (`bg-background`, `bg-card`,\n  `border-border`), they read the theme through the bridge, a file imported\n  right after `theme.css`: `@import \"\u003Ckit>\u002Ftokens\u002Fbridge-shadcn.css\";`, with\n  the real path. A project with none leaves it out.\n- A `:root` or `.dark` block in the entry CSS itself comes after every import\n  and wins over it. An install of 0.3.0 or earlier wrote the bridge there\n  (references such as `--background: var(--md-sys-color-background)`, lines\n  such as `--ring: var(--ring);` inside `@theme`, four `--radius-*` lines):\n  delete them and import the bridge file instead. If either block holds a\n  `--md-sys-color-*` value, or the file has an `@theme inline` block setting\n  `--color-primary` and the like, it is from an older install still and\n  overrides the theme: delete those declarations too. The same goes for the\n  bridged names under a `@media (prefers-color-scheme: dark)` rule of the\n  project's own: the theme owns both schemes.\n- Load the font the theme names (see \"Fonts go through a hook\" in\n  `design-md.md`). The theme does not fetch it.\n- Tailwind scans markdown: if junk utilities appear, exclude the theme\n  folder's `.md` with `@source not \"..\u002Ftheme\u002FDESIGN.resolved.md\";`.\n- If the entry CSS scans the source folder the kit is in, exclude the kit's\n  files that are not components, each with `@source not` and the real path\n  in place of `\u003Ckit>`: `\u003Ckit>\u002Ftokens`, `\u003Ckit>\u002FDESIGN.md`,\n  `\u003Ckit>\u002FRELEASE.json`, `\u003Ckit>\u002Fchanged.mjs`, `\u003Ckit>\u002FLICENSE`, and the\n  `releases` folder beside them where an adapter or the preset brought one.\n  The theme files still reach the build through the imports. Leave\n  `\u003Ckit>\u002Futils.ts` scanned: it holds the focus ring's classes.\n\nBuild the project, then look at it in both schemes.\n\n### See every component under the theme\n\nThe project's own pages show the components it uses. The kit's catalog shows\nall of them, and it can draw them under this project's theme without the\ntheme leaving the browser:\n\n1. Open the catalog. It is served at the root of the address the kit was\n   installed from: take the `@ds` entry of `registries` in the project's\n   `components.json` and cut it before `r\u002F{name}.json`. Add\n   `?path=\u002Fstory\u002Fmd3-your-theme--page` to land on the page\n   **MD3 \u002F Your theme**. If nothing is served there yet, or to work offline,\n   run `npm run storybook` in a checkout of the kit's own repository and open\n   the same page.\n2. Hand it, by the picker or by dropping the files on the page, either\n   `theme\u002Ftheme.css` and `theme\u002Ftheme.v4.css` together (from the project's\n   `theme\u002F` folder), or the project's `DESIGN.md` alone. One of the two\n   stylesheets alone is refused: the theme is both.\n3. Open any story. Switch light and dark with the toolbar's **Theme**; the\n   toolbar's **Preset** reads \"Your theme (handed)\" while the theme draws,\n   and Preset → Material shows the kit's default again for comparison.\n\nTell the person what the page says it does not do: it loads no font (a family\nthe theme names draws only if the machine has it, else the stack behind it),\nand it obeys the toolbar for dark whatever `--md3-dark-mode` says. Handed a\n`DESIGN.md`, the page lists the generator's warnings, contrast included; read\nthem as in step 4. Nothing is uploaded: the files are read in the browser and\nkept in its storage until \"Forget this theme\".\n\n## 6. Keep it true\n\nCommit `DESIGN.md` and the three files in `theme\u002F` together. In the project's\nCI, run `theme:generate` and fail on a diff of `theme\u002F`, so the theme is\nalways its DESIGN.md's.\n\n## Taking a kit update\n\nThe project's theme is in `theme\u002F`, where no item of the kit writes, so an\nupdate cannot touch it. The kit's own files are another matter: the CLI keeps\nno record of what it installed, so it cannot tell a file the kit changed from\na file the project edited. A plain `npx shadcn add @ds\u002Fds` asks about the\nfirst kit file that differs, defaulting to No, even under `-y`; with no one to\nanswer, it writes nothing at all, or waits for ever. So an update takes the\nkit's files whole and lets git show what moved. **Before it, ask the kit which\nof its files the project changed:**\n\n```bash\nnode \u003Ckit>\u002Fchanged.mjs\n```\n\nIt compares each kit file, and each skill, with the release it was installed\nfrom, which `\u003Ckit>\u002FRELEASE.json` records. It writes nothing and merges\nnothing. **Its last line is the update command for what this project holds:\nkeep it for step 2.** Its exit code says which answer it gave:\n\n- **0**: no recorded file of what the project holds differs or is missing.\n  Step 3 has nothing to put back.\n- **1**: it lists files in three groups. `changed`: the text differs, and\n  step 2 loses that edit: these are the files to put back in step 3.\n  `whitespace`: the same text laid out differently, which is a formatter or\n  an indent, and also a change of spaces inside a string or a class list;\n  step 2 puts the kit's layout back. `missing`: a file of the whole install,\n  or of an adapter or preset the project holds, is not there; step 2 brings\n  it back, so delete it again if the project removed it on purpose. Keep the\n  list.\n- **2**: it cannot tell, and says why. There is no `\u003Ckit>\u002FRELEASE.json`: the\n  kit was installed before 0.3.0, and the update that follows brings the\n  record. Or `components.json` makes the CLI rewrite the files as it installs\n  them (`tsx: false`, a Tailwind prefix, `cssVariables: false`). Then the\n  update is as below, and `git diff` alone says what moved.\n\nThe whole install does not bring the three adapters (`@ds\u002Fnext-adapter`,\n`@ds\u002Freact-router-adapter`, `@ds\u002Freact-hook-form-adapter`) or the Editorial\npreset (`@ds\u002Fpreset-editorial`): a project asks for each by name. The check\nknows which of them the project holds, and says two more things that do not\nchange the exit code:\n\n- `Not installed, and no finding`: those of which nothing is here, in one\n  line. `node \u003Ckit>\u002Fchanged.mjs --missing` names every recorded file that is\n  not here, with its item and whether the project holds it.\n- `behind`: one the project holds at an earlier release than the kit's\n  other files, because an update named only `@ds\u002Fds`. The command on the\n  check's last line takes it.\n\nWhat it cannot know: a file the project wrote beside the kit is not looked\nat; an adapter or preset installed at 0.3.0 has no record of its own, so if\nits file differs it is listed as `changed` and the check says it may be\nbehind instead; and a formatter that moves more than whitespace (quotes,\ncommas, parentheses) makes every file it touched `changed`, so keep `\u003Ckit>`\nand `.claude\u002Fskills\u002F` out of the project's formatter and linter (one\n`ignores` entry in an ESLint flat config, one line each in\n`.prettierignore`). Nothing is set aside: a comment put at the top of a kit file\n(`\u002F\u002F @ts-nocheck`) is listed like any edit. A project that has no `\u003Ckit>\u002Fchanged.mjs` gets it alone, with no\nother file touched, by `npx shadcn add @ds\u002Fchanged`.\n\n1. Commit, or stash, everything first. The working tree must be clean: the\n   next step's diff is the update.\n2. Take the kit's files whole, with the command the check printed. For a\n   project that holds no adapter and no preset it is\n\n   ```bash\n   npx shadcn add @ds\u002Fds --overwrite -y\n   ```\n\n   and for one that holds some, each is named in it, or it stays at the old\n   release:\n\n   ```bash\n   npx shadcn add @ds\u002Fds @ds\u002Fnext-adapter @ds\u002Freact-hook-form-adapter --overwrite -y\n   ```\n\n   Every kit file that differs is replaced. The project's `DESIGN.md`,\n   `theme\u002F` and the entry CSS's imports are no item's target and stay as they\n   are.\n3. Read `git status` and `git diff`: it is what the update changed. A kit\n   file the project had edited (the ones the check listed under `changed`;\n   see the `ds-build` skill) shows the project's own edit removed, mixed with\n   the kit's changes: put the project's edit back by hand, keeping the kit's\n   changes. A file the project never edited needs nothing.\n\nSteps 4 and 5 are for a project that generated a theme of its own (it has a\n`DESIGN.md`, a `theme\u002F` folder and the `theme:generate` script). A project\nstill on the kit's default theme has none of the three and stops at step 3:\nbuild, then commit.\n\n4. `npm run theme:generate`. The kit's `theme.v4.css` is the template, so a\n   new scale or utility in the kit reaches the project's copy here.\n5. Lint both files again and read the diff of `theme\u002F`: it is what the update\n   changed in the project's look. Build, then commit.\n\n## The project's design system in Claude\n\nClaude can hold a design system for a project, and apply it when it designs.\nWhen the person asks for one, or asks why a design does not look like the\nproject:\n\n- **It is the project's own, built from this project**: the components in\n  `\u003Ckit>\u002F`, the theme folder and `DESIGN.md`. The kit publishes none, so\n  there is none to look for or to install. One shared by the kit would wear\n  the kit's neutral look and change with the kit's releases.\n- **The look goes one way**: `DESIGN.md`, then the generator (step 3), then\n  the design system. A look found while designing is written into\n  `DESIGN.md` first (step 2) and generated; the design system is then\n  updated from the project. Never copy values from a design back into the\n  theme folder.\n- **Update it when the project's look or its kit changes**: after step 6,\n  and after \"Taking a kit update\". It does not follow the project by itself,\n  and the person chooses when.\n- **How it is created and updated is Anthropic's to say, and it moves.**\n  Read [Set up your design system](https:\u002F\u002Fsupport.claude.com\u002Fen\u002Farticles\u002F14604397) on Anthropic's help centre and\n  follow the route it gives for a design system that lives in code. The\n  same page says which plans have one.\n\n## What this skill does not change\n\nA look that tokens cannot reach (a field's label position, a component's\nanatomy) is an edit of a kit file, allowed and priced: see the `ds-build`\nskill, \"What a project may change\".\n","# ds-theme: the project's look comes from its DESIGN.md\n\nThe project decides its look in one file, `DESIGN.md` at its root. The kit's\ngenerator turns that file into the theme the components read. Nobody edits a\ngenerated file: the next generation writes it again. And a look is not what\na kit file is edited for: that edit is allowed but priced (the `ds-build`\nskill, \"What a project may change\"), and `DESIGN.md` reaches the look for\nfree.\n\n`\u003Ckit>` below is the kit's folder in this project: the `ds` folder under the\n`ui` alias of `components.json` (`src\u002Fcomponents\u002Fui\u002Fds` in most projects).\nFind it once, then read every `\u003Ckit>\u002F…` path with it.\n\n| File                              | Whose   | What it is                                                                 |\n| :-------------------------------- | :------ | :------------------------------------------------------------------------- |\n| `DESIGN.md`                       | project | The look, as decided. The only file edited                                 |\n| `theme\u002Ftheme.css`                 | project | Generated: the 49 colour roles in both schemes, the font hooks             |\n| `theme\u002Ftheme.v4.css`              | project | Generated: the Tailwind mapping with the project's type, corners, motion   |\n| `theme\u002FDESIGN.resolved.md`        | project | Generated: the complete DESIGN.md, every value filled in. Read it, never edit it |\n| `\u003Ckit>\u002FDESIGN.md`                 | kit     | The kit's neutral default, the starting file. Copied, not changed: an update rewrites it |\n| `\u003Ckit>\u002Ftokens\u002Ftheme.css`          | kit     | The default theme, what the project shows until it generates its own       |\n| `\u003Ckit>\u002Ftokens\u002Ftheme.v4.css`       | kit     | The default mapping, and the template the generator writes the project's from |\n| `\u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs` | kit     | The generator's command                                                    |\n| `\u003Ckit>\u002Ftokens\u002Fdesign-md.mjs`      | kit     | The derivation it runs                                                     |\n\nWhat every name in a DESIGN.md means to the kit, what is ignored and what is\nrefused is in `design-md.md`, beside this file\n(`.claude\u002Fskills\u002Fds-theme\u002Fdesign-md.md`). Read it before writing a role, a\ntype value or the reference block.\n\nIf `\u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs` is missing, the whole kit was not\ninstalled: run `npx shadcn add @ds\u002Fds` first.\n\n## 1. Start from a file\n\nIf the project has no `DESIGN.md` at its root, copy the kit's:\n\n```bash\ncp \u003Ckit>\u002FDESIGN.md DESIGN.md\n```\n\nIf it has one, keep it: it is the project's decision. Never overwrite it with\nthe kit's, and never write the project's look into `\u003Ckit>\u002FDESIGN.md`, which an\nupdate replaces.\n\n## 2. Write the brief into it\n\nTurn the brief into tokens in the front matter, and say why in the prose. The\nprose is for people and for the next agent; the generator reads only the front\nmatter and one CSS block.\n\n- **`name`, `description`**: the project's, not the kit's.\n- **`scheme`**: `light` or `dark`, the scheme the written colours belong to. A\n  brief that is dark by nature (cyberpunk, a terminal, a cinema) writes\n  `scheme: dark`; the light scheme is then derived from the keys. Always\n  write it: with none, the generator reads it from the file's ground and\n  lists that as assumed.\n- **`colors`**: write `seed`: with none, the generator reads it from\n  `primary` and lists that as assumed. Add `primary-key`, `secondary-key`,\n  `tertiary-key` for the brief's main colours, `neutral-key` to tint the\n  surfaces. Then write a role (`primary`, `surface`, `on-surface`, …) only\n  where an exact colour matters: a written role holds in the written scheme\n  only, a key holds in both.\n- **`typography`**: at least `fontFamily` on `display-large` and\n  `body-large`. The first is the brand face (display, headline, title), the\n  second the plain face (body, label), and a role that writes no family keeps\n  its face's. A role that writes another family takes it (labels in a squared\n  face under running text in a reading face): each family is one more font\n  the project loads. No `typography` at all means Roboto.\n- **`rounded`**: the six corners. Sharp looks lower them all; `full` stays a\n  pill unless the brief wants square buttons.\n- **`## Reference CSS`** in the body: elevation (a glow instead of a shadow, a\n  hairline, `none`), state layer opacities, easings, durations, and\n  `--md3-dark-mode: class` or `system`.\n- **The prose**: replace the kit's sections with the project's own (Overview,\n  Colors, Typography, and whatever the brief needs). Remove what speaks of the\n  kit's default.\n\nA DESIGN.md that arrives from elsewhere, or a brief with colour names of its\nown, is mapped by you onto `seed`, the keys and the 49 roles: see \"Colour\nnames that are not the kit's\" in `design-md.md`. The other names may stay in\nthe file. They are ignored and listed as warnings. A file in the format's own\nwords (no `scheme`, no `seed`, sizes written `title-md` and `rounded.sm`)\ngenerates as it is, with what was assumed listed: take that as a first\ndrawing, then write `scheme` and `seed` into the file.\n\n## 3. Generate\n\n```bash\nnpx tsx \u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs DESIGN.md --out theme\n```\n\nIt writes `theme\u002Ftheme.css`, `theme\u002Ftheme.v4.css` and\n`theme\u002FDESIGN.resolved.md`, and prints one line naming them with the number of\nwarnings. Record the command once in the project's `package.json`, with the\nreal path in place of `\u003Ckit>`:\n\n```json\n{ \"scripts\": { \"theme:generate\": \"tsx \u003Ckit>\u002Ftokens\u002Fgenerate-theme.mjs DESIGN.md --out theme\" } }\n```\n\nNever pass `--out \u003Ckit>\u002Ftokens`: those are the kit's files and an update\nwrites over them.\n\n## 4. Read the warnings\n\nEach `warning:` line on stderr is something the file says that is not in the\ntheme, or a pair that reads badly. They are also in `## Generator warnings`\nat the end of `theme\u002FDESIGN.resolved.md`. For each one, decide:\n\n- **an unknown name** (`colors.brand-pink`, `typography.h1`, `rounded.pill`):\n  map it to a name the kit reads, or leave it and say it is ignored;\n- **assumed** (`scheme`, `colors.seed`): the file wrote none and the kit read\n  it from the token the line names. Write the key into DESIGN.md, the value\n  the line gives or the one the brief means;\n- **a value with no variable** (a tracking on a role Material gives none):\n  not applied; drop it or accept it. A weight is applied on every role;\n- **poor contrast**: a written role under 4.5:1 against its pair. Fix the\n  role or write its partner. Do not leave it;\n- **the reference block was not read**: fix the heading, the `css` fence or\n  the `:root` selector.\n\nExit code 1 with nothing written means the file was refused: no front matter,\nno `scheme` and no `background` or `surface` to read one from, no `seed` and\nno `primary`, a colour that is not a hex, or a type value, a\ncorner, a family or a reference value that is not one value of its kind (a\nsize with no unit, an easing written as a `var()`). The message names the\ntoken and says what to write.\n\nThen lint both files with the format's own linter:\n\n```bash\nnpx designmd lint DESIGN.md\nnpx designmd lint theme\u002FDESIGN.resolved.md\n```\n\nBoth must end with `\"errors\": 0`. The linter's `missing-primary` warning on\n`DESIGN.md` only says the file writes keys and no `primary` role: the kit\nderives it, and the resolved file has it.\n\n## 5. Point the entry CSS at the theme\n\nThe whole install writes nothing into the entry CSS, at a first install or\nat an update: the theme is whatever that file imports. Replace the kit's two theme imports with the project's (paths\nare relative to the entry CSS; here it is `src\u002Findex.css`):\n\n```css\n@import \"tailwindcss\";\n@import \"..\u002Ftheme\u002Ftheme.css\";\n@import \"..\u002Ftheme\u002Ftheme.v4.css\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:where(.dark, .dark *));\n```\n\n- Before a theme of its own, the same two lines import\n  `\u003Ckit>\u002Ftokens\u002Ftheme.css` and `\u003Ckit>\u002Ftokens\u002Ftheme.v4.css`. Import one pair,\n  never both.\n- Every `@import` stays above any other at-rule. Vite drops an `@import` that\n  comes after `@custom-variant` or `@source`, silently.\n- With `--md3-dark-mode: class` hold one `@custom-variant dark` line, exactly\n  as above, and switch by putting `dark` on `\u003Chtml>`. A project initialised\n  by shadcn has `@custom-variant dark (&:is(.dark *));`, which misses the\n  element that carries the class: replace it. With `system`, remove the line\n  altogether: Tailwind's `dark:` then follows the system setting, as the\n  theme does.\n- If the project has stock shadcn components (`bg-background`, `bg-card`,\n  `border-border`), they read the theme through the bridge, a file imported\n  right after `theme.css`: `@import \"\u003Ckit>\u002Ftokens\u002Fbridge-shadcn.css\";`, with\n  the real path. A project with none leaves it out.\n- A `:root` or `.dark` block in the entry CSS itself comes after every import\n  and wins over it. An install of 0.3.0 or earlier wrote the bridge there\n  (references such as `--background: var(--md-sys-color-background)`, lines\n  such as `--ring: var(--ring);` inside `@theme`, four `--radius-*` lines):\n  delete them and import the bridge file instead. If either block holds a\n  `--md-sys-color-*` value, or the file has an `@theme inline` block setting\n  `--color-primary` and the like, it is from an older install still and\n  overrides the theme: delete those declarations too. The same goes for the\n  bridged names under a `@media (prefers-color-scheme: dark)` rule of the\n  project's own: the theme owns both schemes.\n- Load the font the theme names (see \"Fonts go through a hook\" in\n  `design-md.md`). The theme does not fetch it.\n- Tailwind scans markdown: if junk utilities appear, exclude the theme\n  folder's `.md` with `@source not \"..\u002Ftheme\u002FDESIGN.resolved.md\";`.\n- If the entry CSS scans the source folder the kit is in, exclude the kit's\n  files that are not components, each with `@source not` and the real path\n  in place of `\u003Ckit>`: `\u003Ckit>\u002Ftokens`, `\u003Ckit>\u002FDESIGN.md`,\n  `\u003Ckit>\u002FRELEASE.json`, `\u003Ckit>\u002Fchanged.mjs`, `\u003Ckit>\u002FLICENSE`, and the\n  `releases` folder beside them where an adapter or the preset brought one.\n  The theme files still reach the build through the imports. Leave\n  `\u003Ckit>\u002Futils.ts` scanned: it holds the focus ring's classes.\n\nBuild the project, then look at it in both schemes.\n\n### See every component under the theme\n\nThe project's own pages show the components it uses. The kit's catalog shows\nall of them, and it can draw them under this project's theme without the\ntheme leaving the browser:\n\n1. Open the catalog. It is served at the root of the address the kit was\n   installed from: take the `@ds` entry of `registries` in the project's\n   `components.json` and cut it before `r\u002F{name}.json`. Add\n   `?path=\u002Fstory\u002Fmd3-your-theme--page` to land on the page\n   **MD3 \u002F Your theme**. If nothing is served there yet, or to work offline,\n   run `npm run storybook` in a checkout of the kit's own repository and open\n   the same page.\n2. Hand it, by the picker or by dropping the files on the page, either\n   `theme\u002Ftheme.css` and `theme\u002Ftheme.v4.css` together (from the project's\n   `theme\u002F` folder), or the project's `DESIGN.md` alone. One of the two\n   stylesheets alone is refused: the theme is both.\n3. Open any story. Switch light and dark with the toolbar's **Theme**; the\n   toolbar's **Preset** reads \"Your theme (handed)\" while the theme draws,\n   and Preset → Material shows the kit's default again for comparison.\n\nTell the person what the page says it does not do: it loads no font (a family\nthe theme names draws only if the machine has it, else the stack behind it),\nand it obeys the toolbar for dark whatever `--md3-dark-mode` says. Handed a\n`DESIGN.md`, the page lists the generator's warnings, contrast included; read\nthem as in step 4. Nothing is uploaded: the files are read in the browser and\nkept in its storage until \"Forget this theme\".\n\n## 6. Keep it true\n\nCommit `DESIGN.md` and the three files in `theme\u002F` together. In the project's\nCI, run `theme:generate` and fail on a diff of `theme\u002F`, so the theme is\nalways its DESIGN.md's.\n\n## Taking a kit update\n\nThe project's theme is in `theme\u002F`, where no item of the kit writes, so an\nupdate cannot touch it. The kit's own files are another matter: the CLI keeps\nno record of what it installed, so it cannot tell a file the kit changed from\na file the project edited. A plain `npx shadcn add @ds\u002Fds` asks about the\nfirst kit file that differs, defaulting to No, even under `-y`; with no one to\nanswer, it writes nothing at all, or waits for ever. So an update takes the\nkit's files whole and lets git show what moved. **Before it, ask the kit which\nof its files the project changed:**\n\n```bash\nnode \u003Ckit>\u002Fchanged.mjs\n```\n\nIt compares each kit file, and each skill, with the release it was installed\nfrom, which `\u003Ckit>\u002FRELEASE.json` records. It writes nothing and merges\nnothing. **Its last line is the update command for what this project holds:\nkeep it for step 2.** Its exit code says which answer it gave:\n\n- **0**: no recorded file of what the project holds differs or is missing.\n  Step 3 has nothing to put back.\n- **1**: it lists files in three groups. `changed`: the text differs, and\n  step 2 loses that edit: these are the files to put back in step 3.\n  `whitespace`: the same text laid out differently, which is a formatter or\n  an indent, and also a change of spaces inside a string or a class list;\n  step 2 puts the kit's layout back. `missing`: a file of the whole install,\n  or of an adapter or preset the project holds, is not there; step 2 brings\n  it back, so delete it again if the project removed it on purpose. Keep the\n  list.\n- **2**: it cannot tell, and says why. There is no `\u003Ckit>\u002FRELEASE.json`: the\n  kit was installed before 0.3.0, and the update that follows brings the\n  record. Or `components.json` makes the CLI rewrite the files as it installs\n  them (`tsx: false`, a Tailwind prefix, `cssVariables: false`). Then the\n  update is as below, and `git diff` alone says what moved.\n\nThe whole install does not bring the three adapters (`@ds\u002Fnext-adapter`,\n`@ds\u002Freact-router-adapter`, `@ds\u002Freact-hook-form-adapter`) or the Editorial\npreset (`@ds\u002Fpreset-editorial`): a project asks for each by name. The check\nknows which of them the project holds, and says two more things that do not\nchange the exit code:\n\n- `Not installed, and no finding`: those of which nothing is here, in one\n  line. `node \u003Ckit>\u002Fchanged.mjs --missing` names every recorded file that is\n  not here, with its item and whether the project holds it.\n- `behind`: one the project holds at an earlier release than the kit's\n  other files, because an update named only `@ds\u002Fds`. The command on the\n  check's last line takes it.\n\nWhat it cannot know: a file the project wrote beside the kit is not looked\nat; an adapter or preset installed at 0.3.0 has no record of its own, so if\nits file differs it is listed as `changed` and the check says it may be\nbehind instead; and a formatter that moves more than whitespace (quotes,\ncommas, parentheses) makes every file it touched `changed`, so keep `\u003Ckit>`\nand `.claude\u002Fskills\u002F` out of the project's formatter and linter (one\n`ignores` entry in an ESLint flat config, one line each in\n`.prettierignore`). Nothing is set aside: a comment put at the top of a kit file\n(`\u002F\u002F @ts-nocheck`) is listed like any edit. A project that has no `\u003Ckit>\u002Fchanged.mjs` gets it alone, with no\nother file touched, by `npx shadcn add @ds\u002Fchanged`.\n\n1. Commit, or stash, everything first. The working tree must be clean: the\n   next step's diff is the update.\n2. Take the kit's files whole, with the command the check printed. For a\n   project that holds no adapter and no preset it is\n\n   ```bash\n   npx shadcn add @ds\u002Fds --overwrite -y\n   ```\n\n   and for one that holds some, each is named in it, or it stays at the old\n   release:\n\n   ```bash\n   npx shadcn add @ds\u002Fds @ds\u002Fnext-adapter @ds\u002Freact-hook-form-adapter --overwrite -y\n   ```\n\n   Every kit file that differs is replaced. The project's `DESIGN.md`,\n   `theme\u002F` and the entry CSS's imports are no item's target and stay as they\n   are.\n3. Read `git status` and `git diff`: it is what the update changed. A kit\n   file the project had edited (the ones the check listed under `changed`;\n   see the `ds-build` skill) shows the project's own edit removed, mixed with\n   the kit's changes: put the project's edit back by hand, keeping the kit's\n   changes. A file the project never edited needs nothing.\n\nSteps 4 and 5 are for a project that generated a theme of its own (it has a\n`DESIGN.md`, a `theme\u002F` folder and the `theme:generate` script). A project\nstill on the kit's default theme has none of the three and stops at step 3:\nbuild, then commit.\n\n4. `npm run theme:generate`. The kit's `theme.v4.css` is the template, so a\n   new scale or utility in the kit reaches the project's copy here.\n5. Lint both files again and read the diff of `theme\u002F`: it is what the update\n   changed in the project's look. Build, then commit.\n\n## The project's design system in Claude\n\nClaude can hold a design system for a project, and apply it when it designs.\nWhen the person asks for one, or asks why a design does not look like the\nproject:\n\n- **It is the project's own, built from this project**: the components in\n  `\u003Ckit>\u002F`, the theme folder and `DESIGN.md`. The kit publishes none, so\n  there is none to look for or to install. One shared by the kit would wear\n  the kit's neutral look and change with the kit's releases.\n- **The look goes one way**: `DESIGN.md`, then the generator (step 3), then\n  the design system. A look found while designing is written into\n  `DESIGN.md` first (step 2) and generated; the design system is then\n  updated from the project. Never copy values from a design back into the\n  theme folder.\n- **Update it when the project's look or its kit changes**: after step 6,\n  and after \"Taking a kit update\". It does not follow the project by itself,\n  and the person chooses when.\n- **How it is created and updated is Anthropic's to say, and it moves.**\n  Read [Set up your design system](https:\u002F\u002Fsupport.claude.com\u002Fen\u002Farticles\u002F14604397) on Anthropic's help centre and\n  follow the route it gives for a design system that lives in code. The\n  same page says which plans have one.\n\n## What this skill does not change\n\nA look that tokens cannot reach (a field's label position, a component's\nanatomy) is an edit of a kit file, allowed and priced: see the `ds-build`\nskill, \"What a project may change\".\n",{"name":5,"description":7},"main","2c3b65dc5afd9cba060388bacf97f24a7208d1ee","apps\u002Fweb\u002F.claude\u002Fskills\u002Fds-theme",0,"https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia","https:\u002F\u002Fgithub.com\u002Femyann","Senior Software Engineer","2026-11-15 05:55:45",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add emyann\u002Fnemia --skill ds-theme",{"tool":38,"command":39},"bunx","bunx skills add emyann\u002Fnemia --skill ds-theme",{"tool":41,"command":42},"pnpm","pnpm dlx skills add emyann\u002Fnemia --skill ds-theme","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fapps\u002Fweb\u002F.claude\u002Fskills\u002Fds-theme\u002FSKILL.md",true,[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"design-md.md","REFERENCE","参考文档",21907,"https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fapps\u002Fweb\u002F.claude\u002Fskills\u002Fds-theme\u002Fdesign-md.md",[53,60,67,74,81,88],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7BGEY7EKSRDFAB7B9567QKJ","groom-the-inbox","Read each card in play in the inbox against the repository and say, per card, done (the commit on the base that landed it), replaced (the decision or card that did), stale (each fact that moved, what it said and what it says now) or standing, reading closely only what the period touched. For the janitor's step, which proposes and never acts: a person removes or amends each card by the command the check writes.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fgroom-the-inbox\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7B4AD0ZJYZ3HAJCCBM4CPTY","write-a-spec","Turn an accepted intent into a spec an engineer can build from in this repository: the goal restated, the approach and why, every path it touches, the steps, the tests that prove it, the risks, and what is still open. For a step that designs a change before anyone builds it.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fwrite-a-spec\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7B4A88P2FKWCS1RND507WHE","review-a-change","Review a change in this repository as a second engineer would: against its intent and spec, by reading the diff and the suite's verdict, with findings that name the file, the line and what goes wrong. For a read-only step that decides whether the work goes round again.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Freview-a-change\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7B4A2HFW8F53E390A2KM0R8","read-the-stats","Read a factory's stats since the janitor's last run, against the same length of time before it, write a short report, and propose one correction per card — an allow or deny by name, a line in an agent's body or a skill, or a refusal kept on purpose — each with the numbers behind it, never one already in the inbox. For the janitor's step, which proposes and never acts.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fread-the-stats\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7B49Z4GJ2G8T76X744YHAAN","land-a-branch","Land a run's result on the base branch in this repository's own checkout, the way the step says it lands: make that one act, read its result, and write the message that records what landed — or change nothing and say why it refused. For a gated ending step (workspace: base).","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fland-a-branch\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7B49TMM0QAWF5WQ0QBXM9BG","implement-a-change","Build a change from its spec in this repository: tests first where a rule is claimed, small commits, the tests of what changed green for the right reason, and each review finding answered in the next round. For a step that writes the code.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fimplement-a-change\u002FSKILL.md",[],[]]