design
| Field | Value |
|---|---|
| Type | Skill |
| Source | ~/.copilot/skills/design/SKILL.md |
| Description | The visual law for any framework — writing/editing CSS, “style this”, “add styles”, Tailwind utility classes, BEM class names, design tokens/CSS custom properties, theming, dark mode, light/dark, multiple themes, print styles/@media print, responsive layout, spacing/padding/margins, motion/transitions, typography/font scale, corner radius, color palette/contrast/WCAG, icon layout (“leading icon”, “trailing icon”, “icon stacking”), border discipline (“nested border”, “borders in borders”), card layout, action button placement, grid layout for icons, content below icon, component APIs/variants/states, design system, developer handoff, 8pt grid, breakpoints. Absorbs css, design-principles, and ui-design-system — CSS mechanics, visual/layout enforcement, and token stewardship all route here. NOT component logic (frontend), prose (technical-writing), or ADR rationale (adr, cited by number). |
Bundled Pages
| Group | Name | Source |
|---|---|---|
| References | Colors | ~/.copilot/skills/design/references/colors.md |
| References | Corner Radius | ~/.copilot/skills/design/references/radius.md |
| References | Foundation: Accessibility | ~/.copilot/skills/design/references/foundation-a11y.md |
| References | Foundation: Docs Hierarchy (Nested Outline) | ~/.copilot/skills/design/references/docs-hierarchy.md |
| References | Foundation: List Indents | ~/.copilot/skills/design/references/lists.md |
| References | Icon Layout and Border Discipline | ~/.copilot/skills/design/references/icon-and-border.md |
| References | Motion | ~/.copilot/skills/design/references/motion.md |
| References | Spacing | ~/.copilot/skills/design/references/spacing.md |
| References | Tokens and Theming | ~/.copilot/skills/design/references/tokens-and-theming.md |
| References | Typography | ~/.copilot/skills/design/references/typography.md |
| References Assets Stylelint | Package | ~/.copilot/skills/design/references/assets/stylelint/package.json |
| References Assets Stylelint | Package Lock | ~/.copilot/skills/design/references/assets/stylelint/package-lock.json |
| References Assets Stylelint | Stylelint.config | ~/.copilot/skills/design/references/assets/stylelint/stylelint.config.mjs |
| References Assets Stylelint Plugins | Index | ~/.copilot/skills/design/references/assets/stylelint/plugins/index.mjs |
| References Css | BEM and Tailwind: One Job Each | ~/.copilot/skills/design/references/css/bem-and-tailwind.md |
| References Css | Comments and Naming | ~/.copilot/skills/design/references/css/comments-and-naming.md |
| References Css | CSS Architecture and Performance | ~/.copilot/skills/design/references/css/architecture.md |
| References Css | CSS Hard Rules | ~/.copilot/skills/design/references/css/hard-rules.md |
| References Css | CSS linting and validation | ~/.copilot/skills/design/references/css/linting.md |
| References Css | Modern CSS: Container Queries, :has(), OKLCH, Cascade Layers | ~/.copilot/skills/design/references/css/modern-layout.md |
| References Css | Print and legal documents | ~/.copilot/skills/design/references/css/print-and-legal.md |
| References Css | Working with Tailwind | ~/.copilot/skills/design/references/css/tailwind-config.md |
| Resources | Lints | ~/.copilot/skills/design/lints.toml |
| Scripts | Check | ~/.copilot/skills/design/scripts/check.sh |
| Scripts | Check_colocation | ~/.copilot/skills/design/scripts/check_colocation.py |
| Scripts | Check_contrast | ~/.copilot/skills/design/scripts/check_contrast.py |
| Scripts | Check_css_budget | ~/.copilot/skills/design/scripts/check_css_budget.py |
| Scripts | Check_theme_completeness | ~/.copilot/skills/design/scripts/check_theme_completeness.py |
| Scripts | Design_token_generator | ~/.copilot/skills/design/scripts/design_token_generator.py |
| Scripts | Lint | ~/.copilot/skills/design/scripts/lint.py |
| Scripts | Lint_css | ~/.copilot/skills/design/scripts/lint_css.sh |
| Scripts | Lint_design_principles | ~/.copilot/skills/design/scripts/lint_design_principles.sh |
| Scripts | Lint_tokens | ~/.copilot/skills/design/scripts/lint_tokens.sh |
Source Content
Design
| Domain | The visual law — how CSS is written, how components lay out, and what the token vocabulary is |
| Role | CSS mechanic + visual-design enforcer + token steward, in one front door |
| Output | Token-driven, theme-safe, symmetric, accessible CSS/Tailwind/component code, gated by scripts/check.sh |
This skill absorbed the former css, design-principles, and ui-design-system skills — their rules live in this skill’s own references/, and nothing invokes them separately. Binding decisions (ADR-001 through ADR-009, ADR-013, ADR-018) live in the adr skill (decision index) — cite the ADR, do not restate it.
Route by task
| You’re… | Read | Gate with |
|---|---|---|
Writing or editing any .css file, BEM, Tailwind utilities | references/css/bem-and-tailwind.md, references/css/architecture.md, references/css/tailwind-config.md | scripts/lint_css.sh |
| Checking the CSS hard rules (tokens, symmetry, margins, dedup) | references/css/hard-rules.md | scripts/lint_css.sh |
| Writing comments or naming classes/HTML | references/css/comments-and-naming.md | - |
| Building any icon-bearing component (leading/trailing icon) | references/icon-and-border.md (ADR-009) | scripts/lint_design_principles.sh |
| Adding or reviewing a border, nested card, or overlay | references/icon-and-border.md (ADR-008) | scripts/lint_design_principles.sh |
| Defining or changing a color, token, or theme (light/dark/multi) | references/tokens-and-theming.md | scripts/check_contrast.py + scripts/check_theme_completeness.py |
| Picking a semantic color class | references/colors.md | scripts/lint_tokens.sh |
| Generating a token set from a brand color | references/tokens-and-theming.md#generating-a-token-set-from-a-brand-color | scripts/design_token_generator.py |
| Sizing type, choosing a font, or applying the type scale | references/typography.md (ADR-003) | scripts/lint_tokens.sh |
| Setting a corner radius | references/radius.md (ADR-002) | scripts/lint_tokens.sh |
| Applying padding, margin, or gap | references/spacing.md | scripts/lint_css.sh |
| Adding a transition or animation | references/motion.md (ADR-004) | scripts/lint_css.sh |
Writing @media print or a legal/court document layout | references/css/print-and-legal.md | - |
| Checking accessibility (contrast, focus, ARIA, touch targets) | references/foundation-a11y.md (ADR-005) | scripts/check_contrast.py |
| Nested docs/MDX prose hierarchy or list indents | references/docs-hierarchy.md, references/lists.md | - |
| Verifying every component has co-located CSS, or CSS budget | references/css/architecture.md | scripts/check_colocation.py + scripts/check_css_budget.py |
| Validating anything already written | - | scripts/check.sh <path> |
References load lazily — a one-line padding fix never pays for the whole token pipeline.
House rules
- Tokens only for color, spacing, and radius (ADR-001, ADR-002, ADR-006). Every color is a CSS custom property; every radius comes from the
[data-radius]scale; every space comes from the 8pt scale. Never a raw hex, Tailwind palette number, or arbitrary pixel value. Seereferences/tokens-and-theming.md,references/radius.md,references/spacing.md. - BEM and Tailwind never own the same responsibility (ADR — house convention, see
references/css/bem-and-tailwind.md). BEM owns identity (variant, state); Tailwind owns arrangement (layout, spacing, one-offs). Never both on the same property of the same element. - Icon-text layout is always a CSS grid (ADR-009).
grid-cols-[auto_1fr]or[auto_1fr_auto], neverflex-colon an icon row. Content never stacks below an icon. Seereferences/icon-and-border.md. - One neutral border per local stack (ADR-008). If the parent already has
border border-border, the child does not add another. Preferbg-muted/40. Seereferences/icon-and-border.md. - Typography is the system stack only, no web fonts (ADR-003).
font-serif/font-bodyresolve to-apple-system, "Segoe UI", system-ui, sans-serif. Hierarchy comes fromui-type-*size/weight tokens. Seereferences/typography.md. - No margins on components; margins live at the layout layer. Components own padding and internal spacing only. See
references/spacing.md. - Print is black and white, one central stylesheet, never per-component. See
references/css/print-and-legal.md. - WCAG 2.2 AA is the floor, AAA the target (ADR-005). 4.5:1 normal text / 3:1 large text and UI components; every interactive element has a visible focus ring; 44×44px touch targets; never color alone. See
references/foundation-a11y.md. - Numbers and currency are always locale-formatted (ADR-013).
formatCurrency/formatNumber/formatPercentat the display layer — never rawtoFixed()or string interpolation. - Never
transition: all; always honorprefers-reduced-motion(ADR-004). Name the exact properties. Seereferences/motion.md. - Co-locate component CSS; never duplicate a rule. Every component folder has its own
.css, even if empty; shared visuals become one reusable class. Seereferences/css/architecture.md. - Multiple themes are the default assumption. A theme is a new selector block re-pointing the same semantic names — never a markup-level class swap. See
references/tokens-and-theming.md.
Don’t use me for
- Component state, data flow, hooks, routing →
frontend(react-engineer). - Prose, Markdown mechanics, Mermaid diagrams →
technical-writing. - The ADR record and rationale behind a rule cited here →
adrskill (this skill cites by number, never restates). - Storybook story shape, argTypes, hierarchy moves →
frontend’s Storybook references. - Product/UX research, personas, journey maps →
ux.
How I work
- Identify the task from the routing table above and load only the reference(s) it points to.
- Apply the house rules — tokens, grid, single border, system font stack, spacing scale, print, motion, a11y.
- Write or edit the CSS/TSX, citing the ADR number for any rule enforced (never restating the ADR’s own text).
- Validate with
scripts/check.sh <path>— it dispatches Stylelint, the Python CSS checks, the icon-grid/border heuristic, and the token heuristic by file type, in one call. Run the narrower individual script instead when only one topic changed. - Fix every reported error; warnings and heuristic flags get a second look, not a dismissal.
Self-rubric (run before I respond)
- Colors, spacing, and radius are tokens only — no hex, palette numbers, or arbitrary values.
- BEM and Tailwind do not own the same property on the same element.
- Every icon row is a CSS grid (
grid-cols-[auto_1fr...]), neverflex-col. - No more than one neutral border per local stack.
- Typography uses the system stack only; hierarchy comes from
ui-type-*tokens. - No
marginon a component; outer spacing lives at the layout layer. - Print survives in black and white from the one central stylesheet.
- Contrast checked (4.5:1 / 3:1 AA) on every token pair touched; focus rings visible; touch targets ≥ 44×44px.
- Transitions name their properties and honor
prefers-reduced-motion. - Every component folder has a co-located
.css; no duplicated rules. -
scripts/check.sh <path>exits 0 (or the narrower script for the one topic that changed).
Validate
scripts/lint.py FILE [FILE ...] (or --git-changed) is the one-command dispatcher — reads lints.toml and runs every registered check whose globs match, skipping the rest. Adding a check is a lints.toml append. Each underlying script (lint_css.sh, check_contrast.py, check_theme_completeness.py, check_css_budget.py, check_colocation.py, lint_design_principles.sh, lint_tokens.sh) still runs standalone.
References
| Topic | File |
|---|---|
Modern CSS: container queries, :has(), OKLCH, cascade layers | references/css/modern-layout.md |
| CSS hard rules (canonical) | references/css/hard-rules.md |
| BEM + Tailwind coexistence | references/css/bem-and-tailwind.md |
| CSS file architecture, co-location, layers | references/css/architecture.md |
| Comments and semantic naming | references/css/comments-and-naming.md |
| Stylelint + the four Python checks | references/css/linting.md |
| Print and legal-document discipline | references/css/print-and-legal.md |
| Tailwind config wiring | references/css/tailwind-config.md |
| Tokens, theming, brand-color generation, component architecture, responsive calc, handoff | references/tokens-and-theming.md |
| Icon-grid (ADR-009) + border discipline (ADR-008) + component patterns | references/icon-and-border.md |
| Accessibility (WCAG, semantic HTML, ARIA, focus, touch targets) | references/foundation-a11y.md |
Spacing scale, --ui-pad-* values, layout primitives | references/spacing.md |
Motion tokens, utility classes, animate-* classes | references/motion.md |
Typography scale, ui-type-* classes, print type | references/typography.md |
| Corner radius presets and component map | references/radius.md |
| Semantic color quick rules | references/colors.md |
| Docs/MDX nested-outline hierarchy | references/docs-hierarchy.md |
| List indent discipline in docs prose | references/lists.md |
| Vendored print/legal/motion/Stylelint assets | references/assets/ |
| One-command validation dispatcher | scripts/check.sh |
| Stylelint wrapper (repo → skill → PATH, graceful skip) | scripts/lint_css.sh |
| WCAG contrast checker | scripts/check_contrast.py |
| Theme-completeness checker | scripts/check_theme_completeness.py |
| Co-location checker | scripts/check_colocation.py |
CSS size + @import-depth budget checker | scripts/check_css_budget.py |
| Icon-grid (ADR-009) + border (ADR-008) heuristic | scripts/lint_design_principles.sh |
| Token/font/radius heuristic (ADR-001/002/003/006) | scripts/lint_tokens.sh |
| Design-token generator from a brand color | scripts/design_token_generator.py |