Design System

Document Design System

The visual layer for HTML documents and slide decks: a token file in, a single self-contained CSS bundle out, with every color pairing checked against WCAG before it ships. This is the theming layer for documents — type scales, reading measure, print roles, light/dark surfaces. It is not a product UI component library; there are no buttons, form states, or component variants here.

When to use this skill

• Theming a report or whitepaper that must render as one self-contained HTML file
• Building a deck theme where type must stay legible at projection distance
• Auditing an existing palette before a public or regulated publication
• Diagnosing dark-mode drift — text that reads fine in light mode and fails in dark
• Standardizing across documents so a series of reports looks like one series
• Answering "does this pass AA?" with a number instead of an opinion

Inputs the skill expects

• A design-token JSON file (or the intent to generate one from assets/sample_tokens.json)
• Brand colors, if any exist — a hex value and where it came from
• Typeface choices plus their fallback stacks (self-contained HTML cannot fetch web fonts)
• The conformance target: AA (default) or AAA
• Which artifacts consume the theme: document, deck, or both
• Whether the output will be printed or exported to PDF

Clarify First

Before generating a theme, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Conformance target (AA vs AAA) — why it changes the output: AAA at 7:1 rules out most saturated mid-tones, so the accent and warning colors must be picked differently from the start
• Print / PDF export required — why it changes the output: print needs a forced light role set and page-break rules; retrofitting them means re-deriving every dark value
• Document or deck — why it changes the output: the type ratio differs (1.25 vs 1.333) and decks need larger minimum sizes for projection
• Existing brand colors — why it changes the output: a fixed brand hex constrains the accent ramp and may force the underline-links decision

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Generate a themed CSS bundle from tokens

1. Copy assets/sample_tokens.json and edit the palette, roles, and scales.
2. Lint the token file first — a malformed ramp produces a valid-looking bundle with inverted colors.
3. Compile the bundle and inline the result into the target HTML document.

python3 markdown-html/design-system/scripts/token_linter.py \
  --input markdown-html/design-system/assets/sample_tokens.json --format text

python3 markdown-html/design-system/scripts/theme_builder.py \
  --input markdown-html/design-system/assets/sample_tokens.json \
  --out build/theme.css --format text

Workflow 2 — Gate a palette on WCAG contrast

1. Declare every real foreground/background combination in the pairings block, each with its usage class.
2. Run the AA gate; it exits non-zero on any failure, so it drops into CI directly.
3. Run --all-pairs to find combinations nobody declared but a stylesheet will eventually produce, and --level AAA --no-gate as an aspirational report.

python3 markdown-html/design-system/scripts/contrast_validator.py \
  --input markdown-html/design-system/assets/sample_tokens.json \
  --level AA --format text

python3 markdown-html/design-system/scripts/contrast_validator.py \
  --input markdown-html/design-system/assets/sample_tokens.json \
  --level AAA --no-gate --format json

Workflow 3 — Audit and repair an inherited theme

1. Run the linter to surface structural rot: non-monotonic ramps, roles present in one mode only, literal hex values that will not respond to theming.
2. Run the validator with --all-pairs to get the full contrast matrix.
3. Fix in this order — ramp order first, then mode parity, then contrast. Ramp and parity errors invalidate the contrast numbers, so fixing contrast first wastes the work.

assets/sample_tokens_legacy.json is a deliberately damaged theme carrying all four failure classes, so this workflow demonstrates real repair rather than a clean run. Expect findings from both commands: the linter reports 4 errors and 5 warnings and exits 2; the validator is pinned to report-only with --no-gate and finds 13 failing pairings.

python3 markdown-html/design-system/scripts/token_linter.py \
  --input markdown-html/design-system/assets/sample_tokens_legacy.json \
  --max-severity warning --format json

python3 markdown-html/design-system/scripts/contrast_validator.py \
  --input markdown-html/design-system/assets/sample_tokens_legacy.json \
  --all-pairs --no-gate --format text

Decision frameworks

Type ratio selection

Use 1.25 for documents and 1.333 for decks. A document needs 7-8 usable steps from caption to H1; at 1.5 the top of that range is 8.5x the base, which no report can place on a page. Escape hatch: a single-page poster or title card can use 1.5 because it has one heading and no hierarchy to preserve.

Contrast usage classes

Classify honestly. A border that is the only thing separating two data regions is ui, not decor. The 1.5:1 decor floor is not a WCAG number — it is the point below which a rule stops being visible on a mid-quality screen, so it fails at its decorative job too.

Contrast targets beyond the minimum

[RECOMMENDED] Do not use pure black on pure white. 21:1 is the maximum and it is worse than ~16:1 for extended reading — glyph edges bleed on bright displays, and readers with astigmatism report the most discomfort at that pairing.