design-systemby Alireza Rezvani

Design System Skill.

A Claude Code and Codex skill for brand and design-system work: captures brand identity once through a 10-question wizard for later documents and decks.

Brand & Design Systems
Design system

Download OpenDesign View usage guide

alirezarezvani/claude-skills · markdown-html/skills/design-system/SKILL.mdSKILL.md

--- name: design-system description: Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html … --- ## When to invoke ## Onboarding question set (10 questions) ## Hard rules ## Derived 12-token palette ## Forcing-question library (Matt Pocock grill-with-docs pattern) ## Customization in use (worked example)

Front matter and section headings read from the upstream file on 2026-09-14 · 11,234 characters in full

01 What it does

What the design-system Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

The design-system skill is the shared brand owner for the markdown-html plugin. It captures brand identity once through a 10-question onboarding wizard — primary and accent HEX values, heading and body Google Fonts, a design style (editorial, technical, minimal or playful), default output directory, code theme, TOC behavior and an optional company name and logo — then validates body-text and link contrast against WCAG 2.2 AA and derives 12 CSS custom properties in HSL space.

Three stdlib-only Python tools handle onboarding, config loading and palette validation; precedence is project over global over built-in defaults. Every converter (md-document, md-review, md-slides) reads the saved config, so changing a token changes every rendered document.

What it produces

A config file holding the brand and the derived palette, written either globally or into the project.
Twelve CSS custom properties inlined into each converter's style block, such as --md-surface, --md-border, --md-link and --md-warn.
A JSON schema for the config, shipped as an asset for validation.

See the example prompt ↗

How It Works

01
Run Onboarding Once
The skill is the shared brand owner for the markdown-html plugin: md-document, md-review and md-slides all consume the config it writes, so a single run brands every conversion.
02
Answer the Ten Questions
The wizard records default_output_dir, primary and accent HEX, heading and body fonts, design_style, code_theme, toc.behavior and optional company_name and logo_url.
03
Let Validation Gate the Save
brand_palette_validator.validate() runs after every change, so the pair is re-checked on each field edit rather than only at the end of the wizard.
04
Derive the Twelve Tokens
derive_palette() computes tokens such as --md-surface at bg plus or minus 4-6% luminance and --md-text-muted as rgba(text, 0.68), and stores them under derived_palette in the same config file.
05
Resolve Config by Precedence
config_loader.py is the importable loader every converter calls before rendering; it merges project, then global, then built-in defaults, and honours the bypass env.
06
Override or Reset non-interactively
Beyond the wizard, onboard.py takes --defaults, --set key=value, --scope project, --show and --reset, so brand fields can be changed or wiped without walking the questions again.

02 Find your fit

When to Use the design-system Skill

Use the design-system skill in Claude Code or Codex when the job is brand and design-system work of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

A workspace where someone asks to convert markdown to HTML for the first time, so onboarding has never run.
One repository that needs a different brand from the rest of your work and should not inherit the global config.
CI or an ephemeral session that needs zero-touch defaults instead of ten interactive questions.
You already have at least one brand HEX you want applied consistently across HTML conversions.
You want to test a candidate primary and accent against WCAG before committing them to the config.

Know the Boundaries

It is not a full design-token system such as Style Dictionary or Theo; it ships twelve tokens, not a hundred.
It does not host custom fonts — Google Fonts via CDN is the only typography source.
It is not an accessibility audit suite; axe-core or pa11y cover that, and the skill enforces contrast only.
It does not transform existing CSS — the derived palette is injected only into freshly generated HTML.

What to Provide

Default output directoryA path that must be writable; the default is ./markdown-html-out/ and an unwritable or empty value blocks the save.
Brand primary HEXValidated against ^#?[0-9a-fA-F]{6}$; default #0A1628. The forcing-question library recommends a HEX you already use, not a stock blue.
Accent HEX, or blankLeave it blank on a first run to let derivation produce a companion colour; set it explicitly only if a brand kit specifies one.
Heading and body font namesGoogle Font names chosen from 12 safe defaults, with Inter as the default for both roles.
Optional company name and logo URLBoth default to empty strings; the logo URL may be blank and is base64-embedded at render time.

03 Inside the skill

Rules the design-system Skill Gives Claude Code and Codex

7 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Contrast Must Pass or Nothing Saves
Body text on the background and links on the background must both reach 4.5:1 per WCAG 2.2 §1.4.3.
Output Directory Must Be Writable
The wizard walks up to an existing ancestor and checks os.access(parent, os.W_OK); an empty or unwritable path exits with code 3, and output_path_resolver.py applies the same rule per conversion.
Customization Must Change Output
Decorative-only fields fail the design discipline: each consumer has to read the config and render differently when design_style, brand.primary, code_theme or toc.behavior changes.
Precedence Is Fixed
Project config beats global config beats built-in defaults, and the deep-merge preserves nested keys, so overriding brand.primary in a project does not drop typography.heading_font from global.
Bypass Is for Headless Runs Only
MARKDOWN_HTML_NO_CONFIG=1 serves CI, ephemeral test containers and evaluator loops; never set it silently for an interactive user, who will wonder where their tokens went.
Never Use a Vibrant Primary as the Background
A saturated brand primary used directly as brand.bg produces low text contrast; it belongs in the accent slot instead.
Stay Inside the 12-token Taxonomy
Brand semantics do not get encoded in derived_palette outside those twelve tokens; adding one requires a deliberate name, purpose and derivation rule.

04 Put it to work

Install design-system in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add design-system to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/alirezarezvani/claude-skills --skill design-system

Generic skills CLI form for markdown-html/skills/design-system/SKILL.md; the repository may document its own path.

Give the Skill a First Brand and design-system Work Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Set up the brand for this repo: primary #FF6B35, Inter for headings and body, editorial style, sticky-sidebar TOC, and save it per-project. Point the default output at [output directory] and then convert [document.md] with md-document so it comes out branded.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Inspect the effective config with config_loader.py --show, which resolves project over global over defaults.
Confirm the config file exists and that setup_completed_at is set; if it is missing or null, the converter refuses and surfaces onboarding instead.
Spot-check contrast for a candidate pair with brand_palette_validator.py --primary and --accent before committing to a brand.
Verify the bypass behaves as documented by running with MARKDOWN_HTML_NO_CONFIG=1, which returns DEFAULTS only.

In OpenDesign import design-system from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Alireza Rezvani
Repository: github.com/alirezarezvani/claude-skills Branch main
Skill file: markdown-html/skills/design-system/SKILL.md Content checksum recorded at verification; commit 19392f7
License: MIT From LICENSE; SKILL.md says “MIT”.
Repository stars: 25,934 GitHub snapshot taken 2026-09-14 for the whole alirezarezvani/claude-skills repository, which contains 5 skills in this catalog. Not a rating or usage count for design-system.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to invokeSymptom-to-action table: onboard, refuse conversion, project scope, single-field set, reset, defaults, bypass.
Onboarding question set (10 questions)Table of the ten keys, validators and defaults, from output dir to logo URL.
Hard rulesFive numbered rules: WCAG AA gate, writable dir, real customization, fixed precedence, deliberate bypass.
Derived 12-token paletteTable mapping each CSS custom property to its purpose and HSL derivation rule.
Forcing-question library (Matt Pocock grill-with-docs pattern)Five one-per-turn questions with recommended answers and canon citations.
Customization in use (worked example)Bash block showing onboarding, defaults, set, project scope, reset, show and bypass.
AssumptionsFour preconditions: a brand HEX, one-to-two-minute setup, Google Fonts, WCAG AA floor.
Non-goalsWhat it is not: token system, font hosting, dark-mode switcher, audit suite, CSS transformer.
Distinct fromContrasts this validator and onboarding script with the landing and clinical-research versions.
Output artifactNames the global and project JSON paths plus the schema asset.
Anti-patterns (do not)Four failures to avoid: skipping onboarding, vibrant bg, silent bypass, off-taxonomy tokens.
ReferencesWCAG clauses, typography and color books, TOC guidance, sibling scripts.

The Skill's Own Description

“Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html converter to consume. Use before any markdown-html conversion. Triggers on first-run onboarding ("set up the brand", "configure markdown-html", "run onboarding"), on explicit reset ("reset the design system", "re-onboard"), and is checked by every converter via config_loader.py before rendering. Refuses to save if body-text contrast fails AA 4.5:1 or the output dir isn't writable. Precedence is project (./.markdown-html/) > global (~/.config/markdown-html/) > built-in defaults; MARKDOWN_HTML_NO_CONFIG=1 bypasses.”

Front-matter description from SKILL.md. The full file is about 11,234 characters. Read the full file on GitHub.

06 Before you install

Questions About the design-system Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

Do I have to finish onboarding before converting anything?

The converters check the config through config_loader.py, and if it is missing or setup_completed_at is null the conversion is refused and onboarding is surfaced. Until you complete setup, output renders with placeholder defaults: technically functional but unbranded.

Design System

Run design-system on a Real Brand and design-system Work Task.

Download OpenDesign, import design-system from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills