alirezarezvani/claude-skills / markdown-html/skills/design-system
design-system
VerifiedUse when setting up brand settings before the first markdown-to-HTML conversion, or changing them. Runs a 10-question onboarding with onboard.py (colors, fonts, style, TOC) and refuses palettes that fail WCAG AA via brand_palette_validator.py.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
| assets/design_system_schema.json | config | 4.6 KB |
| references/design_token_canon.md | markdown | 4.2 KB |
| references/typography_pairing.md | markdown | 5.2 KB |
| references/wcag_accessibility.md | markdown | 4.3 KB |
| scripts/brand_palette_validator.py | script | 12.0 KB |
| scripts/config_loader.py | script | 4.7 KB |
| scripts/onboard.py | script | 9.8 KB |
references/design_token_canon.md
View on GitHub# Design Token Canon
**Why this exists:** This skill ships 12 CSS custom properties — small by design-system standards. This document explains why 12 is enough, the taxonomy the tokens follow, and the canon they derive from.
## The 12-token taxonomy
| Layer | Tokens | Purpose |
|---|---|---|
| **Surface** | `--md-bg`, `--md-surface`, `--md-border`, `--md-code-bg` | Vertical layering: page bg → cards/callouts → hairlines → fenced code |
| **Text** | `--md-text`, `--md-text-muted` | Body + secondary (captions, metadata) |
| **Accent** | `--md-accent`, `--md-accent-soft` | Brand emphasis (CTA, callout headers); soft for hover backgrounds |
| **Link** | `--md-link`, `--md-link-hover` | Hyperlink + hover state; iteratively contrast-walked |
| **Semantic** | `--md-success`, `--md-warn` | Inline status, callouts, review severity |
Twelve covers every visual decision a long-form document needs. More tokens (e.g. Material Design's hundreds) optimize for design systems that span many UIs; markdown-html spans one artifact type (a generated HTML file) so we don't need the extra.
## Sources
### 1. Salesforce Lightning Design System — *Tokens* (lightningdesignsystem.com)
First widely-adopted token system at scale. Established the layered taxonomy: surface → text → border → accent → semantic. Markdown-html's 12 tokens follow the same layering, scoped down to document-rendering needs.
### 2. Adobe Spectrum — *Color Foundations* (spectrum.adobe.com)
Documents the four roles a brand color plays: bg, accent, text, semantic. Validates the decision to derive accent from primary rather than treat them as independent (Spectrum: "accent should be a tinted, brightness-adjusted variant of the brand color").
### 3. Material Design 3 — *Color Roles* (m3.material.io)
Token taxonomy of `primary`/`onPrimary`/`primaryContainer`/`onPrimaryContainer` etc. We deliberately simplify: a long-form document doesn't need surface containers within accent containers. The 12-token system is the Material taxonomy collapsed to what document rendering actually requires.
### 4. Sara Soueidan — *Color Tokens for Accessible Color Systems* (sarasoueidan.com, 2022)
Argues for contrast-walked link colors: a link in brand accent often fails the 4.5:1 floor against bg; the system must lighten or darken until it passes. Our `_ensure_link_contrast()` is the direct implementation.
### 5. Style Dictionary (amzn.github.io/style-dictionary)
The industry-standard token transformation tool — takes JSON tokens and emits CSS / Swift / Kotlin / Flutter. We deliberately ship JSON tokens compatible with Style Dictionary in case a user wants to extend; we don't depend on it.
### 6. CSS Custom Properties (MDN)
The native browser primitive for runtime-themable styles. Inlining `:root { --md-bg: #...; }` into the generated `<style>` block means the user can override any token by adding their own `:root` override in a custom-CSS section of the document (escape hatch).
### 7. Material Design 2 — *Type Scale* and *Color System* (material.io archive)
Original 8-point grid + modular type scale + tonal palette. We use a smaller subset (just modular scale via `typography.scale_ratio`, default 1.25 = major third) and 12 tokens; same philosophy.
## Why not 8? Why not 50?
- **8 tokens** (the original landing-skill palette) — covers a landing page (hero bg, accent CTA, card bg, card border, off-white text, muted text, glow). Documents need link, link-hover, code-bg, success, and warn that landing doesn't.
- **50 tokens** (Material Design 3 / IBM Carbon) — covers a multi-surface UI with elevated containers, interactive states, focus rings, disabled states. A document is a single surface with text — most of those tokens never render.
Twelve is the smallest number that covers every visual decision a long-form document, code review, or slide deck must make, without inventing decisions the document doesn't have.
## Applied to markdown-html
Every converter inlines the user's `derived_palette` into a `:root { }` block at the top of `<style>`. Every other CSS rule references the variables — no hard-coded colors anywhere. This makes the converters honestly customizable: change `brand.primary` and re-onboard, all 12 tokens re-derive, and the document re-renders with a different brand without any code change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |