What is the vois-tokens skill?
The vois-tokens skill is a SKILL.md in ommakes/Skills that encodes design system rules for an AI coding agent: spacing, typography, color tokens, component patterns, animation and accessibility. It targets UI built with shadcn/ui, Tailwind v4 or StyleX, and Motion, so agents produce consistent UI without guessing.
vois-tokens is a skill for AI coding agents that encodes design system rules covering spacing, typography, color tokens, component patterns, animation and accessibility, so agents produce consistent UI without guessing. It is the third skill in the Vois stack.
It applies to UI built with shadcn/ui, Tailwind v4 or StyleX, and Motion. The agent checks package.json for tailwindcss or @stylexjs/stylex to determine the styling engine before it applies implementation layer rules.
Before the agent writes anything
- Check the component manifest. If a component exists for the job, use it instead of building a new one.
- Check data/tokens.json for the value you need, such as spacing, type scale, color, elevation, icon size or breakpoints. If a token exists, use it and hardcode nothing.
- If neither exists, flag it. Do not invent values or components.
Taste dials
Three dials from 1 to 10 tune the output: VARIANCE for layout asymmetry, MOTION for animation richness and DENSITY for information per screen. They default to 5, 4 and 5, and adjust degree only, within safety, accessibility and hard token rules.
Rules, values and references
Rule statements live in data/vois-rules.json as numbered DS rules, and token values live in data/tokens.json. The references folder holds one file per topic, and the agent reads only the files relevant to what it is building.
Automated checks
A zero dependency detector in scripts mechanically checks the regex verifiable subset of the rules, including DS-SLOP-002 and DS-TABLE-001, and can run as a per-edit hook in Claude Code, Cursor or Codex.
Who the vois-tokens skill is for
Best for
- Components and pages that should conform to a design system built on shadcn/ui, Tailwind v4 or StyleX, and Motion.
- Cursor, Claude Code or v0 workflows where the agent needs spacing, typography, color and accessibility rules written down.
- Marketing surfaces, which get their own type scale and spacing ratios.
Not for
- Opening a live URL in a headless browser and reading back its colors, type, components and W3C design tokens, which the designlang MCP server covers.
- Turning one plain request into design tokens and an atomic component structure, which the design-system-starter skill covers.
- Translating a Figma button spec into React with Tailwind classes such as h-10, px-6 and rounded-md, which the design-to-component-translator skill covers.
How to install Vois Tokens Skill: Design Rules for AI Coding Agents
npx skills add ommakes/Skillsvois_record_rule_usage tool is available, the agent calls it after UI work with the rule IDs it applied. If the tool is not available, that step is skipped.Install the skills
Run the command above. The Skills repository ships the Vois design system skills alongside auxiliary skills.
Read the stack in order
Read vois-patterns, then vois-components, then vois-tokens. Put vois-dataviz between patterns and components for any screen that shows data.
Set up the optional detector
Setup for the per-edit hook and for managing ignores is in
references/hooks.md.
Check that it loaded
Ask your agent to build a component with this skill. Expect it to check the component manifest and data/tokens.json before it writes anything.
Key features
- Rule index
data/vois-rules.jsonholds every numbered[DS-XXX-NNN]rule from the reference files, keyed by id with a category for filtering. - Token values
data/tokens.jsonholds the spacing scale, type scale, easing curves, elevation shadow tiers, icon sizes, breakpoints, contrast minimums and the touch target minimum. - Styling engine checkThe agent checks package.json for
tailwindcssor@stylexjs/stylexbefore it applies implementation rules, and two reference files are engine specific. - Pre-submit checklistA checklist grouped by spacing, typography, color, components, surfaces, animation, accessibility, layout, data tables, CSS and marketing gates the work before it is called done.
- Taste dialsVARIANCE, MOTION and DENSITY tune choices within the allowed range and default to 5, 4 and 5.
- Anti-slop checksDS-SLOP rules flag a centered hero default above VARIANCE 4, a purple to blue AI gradient, three identical feature cards in a row, eyebrow overuse and em dashes in shipped copy.
- Motion rulesUI animations stay under 300ms and large elements under 500ms,
prefers-reduced-motionis handled, and timing and easing come from motion tokens. - Data table rules
references/data-tables.mdcovers one scroll owner per table, sticky header and first column, scrollbar styling and a one-axis wheel lock. - Marketing type and spacingMarketing surfaces use a display face only for display and h2, body text capped at
56ch, and a section gap at least 4x the heading to content gap. - Per-edit detector
scripts/detect.mjschecks the mechanically verifiable subset of the checklist and can run as a per-edit hook.
Frequently asked questions
What is the vois-tokens skill?
It is a SKILL.md in the ommakes/Skills repository that encodes design system rules for AI coding agents. The rules cover spacing, typography, color tokens, component patterns, animation and accessibility, and they apply to UI built with shadcn/ui, Tailwind v4 or StyleX, and Motion. The goal is consistent UI without guessing.
How do I install the vois-tokens skill?
Run npx skills add ommakes/Skills. The command installs from the Skills repository, which holds the Vois stack and auxiliary skills. Each skill works standalone, with no orchestrator or MCP server required. When building UI, read them in order: vois-patterns, vois-components, then vois-tokens, with vois-dataviz between patterns and components for data screens.
Which styling engines does the vois-tokens skill support?
It supports shadcn/ui with Tailwind v4 or StyleX, plus Motion for animation. The agent determines the engine first by checking package.json for tailwindcss or @stylexjs/stylex, or by looking for existing stylex.create usage. Only the Tailwind and StyleX reference files and a few rules tagged for an engine differ. Everything else applies under either.
What do the VARIANCE, MOTION and DENSITY dials do?
VARIANCE biases layout from symmetric grids to asymmetry, MOTION biases how much animation to add, and DENSITY biases spacing toward the tighter or looser end of the 4 and 8 scale. If no dials are passed, the defaults are 5, 4 and 5. Dials adjust degree only, so contrast, touch targets and animation caps hold at every value.
What does the per-edit detector check?
scripts/detect.mjs is a deterministic detector for the mechanically verifiable subset of the Pre-Submit Checklist, plus nine lookalike checks from vois-components. It can run as a per-edit hook in Claude Code, Cursor or Codex. The setup steps and the way to manage ignores are in references/hooks.md.
Where do the rules and token values live?
Rule statements are canonical in data/vois-rules.json, keyed by id with a category and, for engine specific rules, an engines field. Token values are separate in data/tokens.json. The references files restate rules with code examples, and if they disagree with the JSON, the JSON wins. scripts/check-rule-sync.mjs runs in CI to check that the two do not silently disagree.
What happens when a needed token or component is missing?
The agent flags it and does not invent values or components. The skill first checks the component manifest and data/tokens.json, and only when neither has what is needed does it flag the gap. The same applies to any value that is not in the tokens: flag it, don't invent it.
Which AI-looking defaults does the skill flag?
The DS-SLOP rules flag a centered hero default above VARIANCE 4, a purple to blue AI gradient, three identical cards in a row, eyebrows beyond about one per three sections, emoji standing in for icons, more than two consecutive zigzag sections, a spec-sheet table on a marketing surface and em dashes in shipped copy.