What is the humane design-tokens skill?
The design-tokens skill from glebis/humane-agentic-design manages DTCG 2025.10 design tokens with a dependency free Python core. Your AI coding agent scaffolds, validates, merges, resolves and exports them to CSS, and it owns contrast measurement on both APCA Lc and the WCAG ratio.
The design-tokens skill is one of 21 design method skills in glebis/humane-agentic-design. It manages DTCG 2025.10 design tokens with a dependency free Python core that scaffolds, validates, merges, resolves aliases and exports CSS.
It supports the color, dimension, duration, fontFamily, fontWeight, number, typography and shadow types. Outputs are CSS custom properties, a Google Labs DESIGN.md in alpha, a standalone HTML preview and generation prompts.
Layering and storage
A global base and a project override merge into one set, and a theme is one override file merged before use. This layering is a convention of the skill and is not part of the DTCG standard.
Token files are kept visible and committed. Global sets live at ~/design-tokens/<set>/base.tokens.json, and a single set project keeps design.tokens.json and DESIGN.md at the project root.
Contrast measurement
The skill owns all contrast measurement. The tokens contrast command reports every text and background pair on APCA Lc and the WCAG ratio, with body text at Lc 75 or 4.5:1 and non body text at Lc 60 or 3:1.
A suggested fix moves OKLCH lightness only, so the brand hue survives. Pairs can be declared in a community.design-tokens.contrast extension, and colors that cannot be parsed are listed as not measured.
Brand direction and generation prompts
A brand block in the token file holds mood, imageryStyle, subjects, avoid and negativePrompt. The prompt door turns resolved tokens into gpt-image-2 and nano-banana command lines and a tufte report theme.
Who the humane design-tokens skill is for
Best for
- Defining a token set globally or per project and compiling it to CSS variables.
- Checking whether a palette is readable on both APCA and WCAG scales before it ships.
- Producing an on-brand DESIGN.md or context file for other generation skills.
Not for
- A UI framework or an automatic workflow engine; the repository states it is neither.
How to install Humane Design Tokens Skill: DTCG Tokens and Contrast
npx skills add glebis/humane-agentic-designRun the install command
Run
npx skills add glebis/humane-agentic-designfor Codex and other Agent Skills hosts, then choose the scope and installation method.Install as a Claude Code plugin
Run
/plugin marketplace add glebis/humane-agentic-designand then/plugin install humane@humane-agentic-design. Skills are invoked ashumane:<skill>.Install in pi
Run
pi install git:github.com/glebis/humane-agentic-design, thenpi listto confirm.Call the skill
Ask to set up design tokens or check contrast. The skill announces that it is using humane:design-tokens.
Check that it loaded
Ask your agent to check the contrast of a token file. Expect the skill to run the tokens contrast command and report APCA Lc and WCAG ratio for each text and background pair.
Key features
- DTCG token coreA dependency free Python core scaffolds, validates, merges, resolves aliases and exports CSS for DTCG 2025.10 token files.
- Eight token typesSupports color, dimension, duration, fontFamily, fontWeight, number, typography and shadow values.
- Global and project layersMerge layers a project's override file over a global base set, and each theme is kept as its own override file.
- Two contrast scalesThe contrast command reports APCA Lc and the WCAG ratio, and --standard both is the default and requires clearing both.
- Lightness only fixesSuggested fixes walk OKLCH lightness away from the background and keep chroma and hue, so the brand hue survives.
- Declared pairsA community.design-tokens.contrast extension lists the pairs to measure and the tokens to exclude, and a name that resolves to no token is reported.
- CI gatingvalidate with --strict exits 1 on failures, and contrast exits 1 on any failure by itself.
- DESIGN.md outputuse and design-md emit a generated DESIGN.md, and an existing file without the generator marker is left untouched.
- Brand blockA brand extension with mood, imageryStyle, subjects, avoid and negativePrompt feeds the prompt door, backed by a questionnaire for authoring it.
- Live site extractionTokens can be reverse engineered from a shipping site, and templates/monaspace.tokens.json is the worked example.
Frequently asked questions
What is the humane design-tokens skill?
It is the design-tokens skill in glebis/humane-agentic-design, a repository of 21 design method skills. It sets up, validates, resolves and exports DTCG 2025.10 design tokens with a dependency free Python core, and it owns contrast measurement and remediation for token sets.
How do I install the design-tokens skill?
Run npx skills add glebis/humane-agentic-design for Codex and other Agent Skills hosts. In Claude Code run /plugin marketplace add glebis/humane-agentic-design and then /plugin install humane@humane-agentic-design, and invoke the skill as humane:design-tokens. Pi users run pi install git:github.com/glebis/humane-agentic-design. Use pi list to confirm a pi install.
Which contrast standards does it check?
It reports both APCA Lc and the WCAG 2.x ratio for every text and background pair. Body text needs Lc 75 or 4.5:1, and non body text such as links, icons, badges and large text needs Lc 60 or 3:1. The default standard is both, which requires clearing both.
How does it fix a failing color pair?
The suggestion walks OKLCH lightness away from the background until the pair clears, keeping chroma and hue so the brand hue survives. When no lightness on that axis clears the bar, no fix is offered, because chroma or the background has to move and that is a design decision.
Can it gate a build in CI?
Yes. The validate command prints contrast failures as warnings and exits 0, and adding --strict promotes them to errors with exit 1. The contrast command exits 1 on any failure by itself. Run it after merging, once per theme. Declared pairs that resolve to no token also exit non zero.
What does it export?
It exports CSS custom properties, a Google Labs DESIGN.md in alpha, a standalone HTML preview and generation prompts. The prompt door emits gpt-image-2 and nano-banana command lines plus a tufte report theme. Previews are served from a small HTTP server on 127.0.0.1 when run interactively.
What is not supported in version one?
Not in v1 are JSON Pointer $ref, $root, structured color objects, name restriction enforcement, Style Dictionary, Figma and Pencil importers, share bundles and skillify. CSS import covers color, dimension, duration, fontFamily and number, and composite values such as box shadows and gradients are skipped and reported.
Does it overwrite my own DESIGN.md?
No. Before overwriting, an existing DESIGN.md without the generator design-tokens marker is treated as hand written or foreign. The tool warns and leaves it untouched, and you regenerate explicitly with the design-md command and the -o DESIGN.md flag. The generated file carries provenance frontmatter and a do not edit line naming the source.