OneLinersCommand workbench
AI
Back to skills
SKILL.md

Design system implementation skill

Translates an approved design brief into consistent tokens, components, and visual QA.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/design-system/SKILL.md
Claude Code.claude/skills/design-system/SKILL.md
VS Code.github/skills/design-system/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: design-system
description: Implements one component from a supplied semantic-token contract and verifies actual rendered bindings/states. Use when a palette exists but components ignore it; distinguish fidelity, contrast arithmetic and broader accessibility coverage.
license: CC-BY-4.0
compatibility: The complete fictional reference, two HTML files and opaque-sRGB calculator are embedded. Browser for visual/state checks; Node.js 22.13+ only for the optional calculator. No missing DESIGN.md, stylesheet, font or asset dependency.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Design system implementation skill

## Read the approved reference and preserve meaning
Inventory actual components, variants/states, typography, density and accessibility constraints before changing CSS. Resolve the real reference/owner decision; do not invent a brand and apply it globally. Bind roles such as surface/on-surface and action/on-action consistently instead of choosing attractive but semantically unrelated hex values. A missing token/reference is a question, not a license to restyle.

## Complete original reference
The following is the entire fictional exercise contract. It is not a OneLiners redesign or a claim about a user's approved brand. DESIGN.md is an optional project convention, not an automatically recognized agent standard; if a real project uses it, read that actual file and its integration instructions.

```text
Fictional approved reference for this exercise, not OneLiners branding.
Dark review surface #151a21; normal text #f0f4f8; secondary text #aab6c5.
Primary review action background #89b4fa with text #111820.
Error notice background #4f2329 with text #ffdadd and an explicit Error label.
Keyboard focus outline #ffd75f, 3px with 3px offset; no motion is required.
Control spacing 12px, radius 8px, system-ui 16px base; controls can grow with text.
Tokens express surface/on-surface, action/on-action and danger-surface/on-danger roles.
No separate DESIGN.md, token file, font download or asset is needed to run the included HTML.
```

Before — tokens-before.html (intentional drift):

```html
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Owned tokens — negative control</title><style>:root{color-scheme:dark;--surface:#151a21;--on-surface:#f0f4f8;--muted:#aab6c5;--action:#89b4fa;--on-action:#111820;--focus:#ffd75f;--danger-surface:#4f2329;--on-danger:#ffdadd;--space-control:12px;--radius:8px}
*{box-sizing:border-box}body{margin:0;background:var(--surface);color:var(--on-surface);font:1rem/1.5 system-ui,sans-serif}main{max-inline-size:64rem;margin-inline:auto;padding:24px}h1{font-size:1.75rem;line-height:1.2}button,input{font:inherit}button{min-block-size:44px;min-inline-size:44px;padding:var(--space-control);border:1px solid var(--action);border-radius:var(--radius);background:var(--action);color:var(--on-action);cursor:pointer}button:focus-visible,a:focus-visible,input:focus-visible,pre:focus-visible{outline:3px solid var(--focus);outline-offset:3px}a{color:var(--action)}.muted{color:var(--muted)}input{max-inline-size:100%;padding:12px;border:1px solid var(--muted);background:var(--surface);color:var(--on-surface)}p,li{overflow-wrap:anywhere}
@media(forced-colors:active){:root{--surface:Canvas;--on-surface:CanvasText;--muted:CanvasText;--action:ButtonFace;--on-action:ButtonText;--focus:Highlight;--danger-surface:Canvas;--on-danger:CanvasText}button{border-color:ButtonText}a{color:LinkText}}
.muted{color:#596373}#review{background:#e83e67;color:#ffffff;border-color:#e83e67}.notice{padding:16px}.error{background:#e83e67;color:#ffffff}</style></head>
<body><main><h1>Owned semantic-token review</h1><p class="muted">Secondary text still communicates important information.</p><button id="review" type="button">Review changes</button><button id="simulate" type="button">Simulate validation error</button><p id="status" class="notice" role="status">Ready for review.</p></main><script>document.getElementById('simulate').addEventListener('click',()=>{const status=document.getElementById('status');status.className='notice error';status.textContent='Error: a required review is missing.';});document.getElementById('review').addEventListener('click',()=>{const status=document.getElementById('status');status.className='notice';status.textContent='Owned review selected; no change applied.';});</script></body></html>
```

After — tokens-after.html (semantic bindings):

```html
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Owned tokens — semantic bindings</title><style>:root{color-scheme:dark;--surface:#151a21;--on-surface:#f0f4f8;--muted:#aab6c5;--action:#89b4fa;--on-action:#111820;--focus:#ffd75f;--danger-surface:#4f2329;--on-danger:#ffdadd;--space-control:12px;--radius:8px}
*{box-sizing:border-box}body{margin:0;background:var(--surface);color:var(--on-surface);font:1rem/1.5 system-ui,sans-serif}main{max-inline-size:64rem;margin-inline:auto;padding:24px}h1{font-size:1.75rem;line-height:1.2}button,input{font:inherit}button{min-block-size:44px;min-inline-size:44px;padding:var(--space-control);border:1px solid var(--action);border-radius:var(--radius);background:var(--action);color:var(--on-action);cursor:pointer}button:focus-visible,a:focus-visible,input:focus-visible,pre:focus-visible{outline:3px solid var(--focus);outline-offset:3px}a{color:var(--action)}.muted{color:var(--muted)}input{max-inline-size:100%;padding:12px;border:1px solid var(--muted);background:var(--surface);color:var(--on-surface)}p,li{overflow-wrap:anywhere}
@media(forced-colors:active){:root{--surface:Canvas;--on-surface:CanvasText;--muted:CanvasText;--action:ButtonFace;--on-action:ButtonText;--focus:Highlight;--danger-surface:Canvas;--on-danger:CanvasText}button{border-color:ButtonText}a{color:LinkText}}
.notice{padding:16px;border:1px solid var(--muted);border-radius:var(--radius)}.error{background:var(--danger-surface);color:var(--on-danger);border-color:var(--on-danger)}button{margin-block:8px;margin-inline-end:8px}</style></head>
<body><main><h1>Owned semantic-token review</h1><p class="muted">Secondary text still communicates important information.</p><button id="review" type="button">Review changes</button><button id="simulate" type="button">Simulate validation error</button><p id="status" class="notice" role="status">Ready for review.</p></main><script>document.getElementById('simulate').addEventListener('click',()=>{const status=document.getElementById('status');status.className='notice error';status.textContent='Error: a required review is missing.';});document.getElementById('review').addEventListener('click',()=>{const status=document.getElementById('status');status.className='notice';status.textContent='Owned review selected; no change applied.';});</script></body></html>
```

## Verify states and actual colors
Inspect rendered foreground/background for normal/secondary/action/error states, not just variables declared on :root. Activate Simulate validation error, verify visible text and state color pair, then reach Review changes by keyboard and confirm visible focus. The included CSS has no animation; this does not substitute for testing motion/preferences across a real application. Preserve native control semantics and let text grow.

Save the complete calculator as token-contrast.mjs and run node token-contrast.mjs. Its input pairs are included and it performs actual relative-luminance arithmetic; it is not a full CSS/DOM or WCAG auditor.

```js
import assert from "node:assert/strict";
const tokenPairs=[
  {
    "role": "normal text on surface",
    "foreground": "#f0f4f8",
    "background": "#151a21",
    "threshold": 4.5
  },
  {
    "role": "secondary text on surface",
    "foreground": "#aab6c5",
    "background": "#151a21",
    "threshold": 4.5
  },
  {
    "role": "action text",
    "foreground": "#111820",
    "background": "#89b4fa",
    "threshold": 4.5
  },
  {
    "role": "error text",
    "foreground": "#ffdadd",
    "background": "#4f2329",
    "threshold": 4.5
  },
  {
    "role": "focus outline against surrounding surface",
    "foreground": "#ffd75f",
    "background": "#151a21",
    "threshold": 3
  },
  {
    "role": "negative-control secondary text",
    "foreground": "#596373",
    "background": "#151a21",
    "threshold": 4.5
  }
];
function contrastRatio(foreground, background) {
  const luminance = (hex) => {
    assert.match(hex, /^#[0-9a-f]{6}$/i, "only opaque six-digit sRGB colors are supported");
    const rgb = [1, 3, 5].map((index) => parseInt(hex.slice(index, index + 2), 16) / 255).map((value) => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4);
    return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
  };
  const a = luminance(foreground), b = luminance(background);
  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
}
const rows=tokenPairs.map(pair=>({...pair,ratio:contrastRatio(pair.foreground,pair.background),passes:contrastRatio(pair.foreground,pair.background)>=pair.threshold}));
assert.ok(rows.slice(0,5).every(row=>row.passes));
assert.equal(rows[5].passes,false);
assert.equal(contrastRatio('#000000','#ffffff'),21);
console.log(JSON.stringify(rows,null,2));
```

## Worked fidelity and contrast evidence
The supplied reference assigns meanings, not just a list of hex values. Before, the action is hard-coded pink/white rather than action/on-action, and secondary text #596373 on surface #151a21 has ratio 2.877:1. That pair fails the normal-text 4.5:1 threshold; rounding it or calling the text secondary does not exempt informative copy.

The repaired rendered action actually uses rgb(137,180,250) with rgb(17,24,32), matching #89b4fa/#111820. Secondary text is rgb(170,182,197), matching #aab6c5. The real Simulate validation error interaction shows explicit Error text with #ffdadd on #4f2329; it does not communicate state only by a colored fill. Shift+Tab returns focus to Review changes with a visible outline in the declared focus color, and Enter updates only the owned status, not external data.

The actual sRGB calculations are approximately: normal text 15.813, secondary 8.494, action text 8.485 and error text 10.172 to 1. Focus color against the surrounding surface is 12.598 to 1. The program compares full precision against the stated pair threshold before rounding for display. It supports only opaque six-digit sRGB pairs, not alpha/gradients/images, arbitrary CSS color spaces or every component state. The outline test alone is not a complete focus-appearance audit.

Deliver a token/component/state matrix and a small fidelity ledger: which reference was supplied, exact rendered token binding, contrast/state evidence, intentional deviation and owner decision. The full reference, CSS and calculator are included; there is no missing design-tokens.css or DESIGN.md to guess. Forced-color overrides are provided in the example, but an actual forced-colors/screen-reader/device matrix was not executed. Do not label the whole system WCAG-compliant from these pairs or replace an existing product palette without approval.

## Reference and handoff
[W3C minimum-contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) defines the selected normal-text calculation/threshold and its exceptions; informative secondary text is still text. This example uses a separately stated 3:1 comparison for the chosen focus/surface pair, not a universal substitute for all focus criteria. Return the reference version, token aliases, component variants/states, measured bindings, failures/fixes, responsive screenshot proof and actual untested coverage. Do not encode status only in color, suppress native high-contrast behavior or overwrite user content to make a demo match a screenshot.

Real example

Input

Use the complete fictional semantic-token reference and before/after HTML in SKILL.md. Verify actual action/secondary/error/focus colors and interaction, calculate the included opaque-sRGB pairs and distinguish one component's fidelity from a full accessibility claim. No outside token/design file is required.

Expected result

The supplied reference assigns meanings, not just a list of hex values. Before, the action is hard-coded pink/white rather than action/on-action, and secondary text #596373 on surface #151a21 has ratio 2.877:1. That pair fails the normal-text 4.5:1 threshold; rounding it or calling the text secondary does not exempt informative copy.

The repaired rendered action actually uses rgb(137,180,250) with rgb(17,24,32), matching #89b4fa/#111820. Secondary text is rgb(170,182,197), matching #aab6c5. The real Simulate validation error interaction shows explicit Error text with #ffdadd on #4f2329; it does not communicate state only by a colored fill. Shift+Tab returns focus to Review changes with a visible outline in the declared focus color, and Enter updates only the owned status, not external data.

The actual sRGB calculations are approximately: normal text 15.813, secondary 8.494, action text 8.485 and error text 10.172 to 1. Focus color against the surrounding surface is 12.598 to 1. The program compares full precision against the stated pair threshold before rounding for display. It supports only opaque six-digit sRGB pairs, not alpha/gradients/images, arbitrary CSS color spaces or every component state. The outline test alone is not a complete focus-appearance audit.

Deliver a token/component/state matrix and a small fidelity ledger: which reference was supplied, exact rendered token binding, contrast/state evidence, intentional deviation and owner decision. The full reference, CSS and calculator are included; there is no missing design-tokens.css or DESIGN.md to guess. Forced-color overrides are provided in the example, but an actual forced-colors/screen-reader/device matrix was not executed. Do not label the whole system WCAG-compliant from these pairs or replace an existing product palette without approval.

Source evidence

Agent Skills specificationofficialW3C WCAG2.2 — contrast, relative luminance and unrounded thresholdsofficial