Design System

Build design systems with tokens, components, and documentation that scale across teams and products.

Security Scan

The skill's requests and instructions match its stated purpose: it is an instruction-only design-system helper that stores its local memory under ~/design-system/ and does not ask for credentials or install anything.

Purpose & Capability

Name/description (design system tokens, components, docs) align with the instructions and included templates. No unrelated binaries, env vars, or services are requested.

Instruction Scope

SKILL.md and setup.md limit behavior to asking the user questions, advising on patterns, and reading/writing files in ~/design-system/. The skill explicitly states it will not access files outside that directory or make network requests.

Install Mechanism

No install spec and no code files — instruction-only means nothing is downloaded or written by an installer. Lowest-risk install posture.

Credentials

No environment variables, credentials, or config paths are requested. All required state is local and file-based (~/design-system/). Proportional to the claimed functionality.

Persistence & Privilege

The skill persists a memory file under the user's home (~ /design-system/memory.md). This is reasonable for a design-system assistant, but it is persistent data stored on disk — users should be aware of what is written and avoid saving secrets there.

Assessment

This skill appears coherent and low-risk: it only uses local files and includes templates for storing design-system memory at ~/design-system/memory.md. Before installing or using it, consider: 1) inspect the contents of ~/design-system/ if you want to confirm what the agent wrote; 2) do not paste secrets or credentials into the memory files (they are persistent); 3) the skill claims it won’t make network requests, but the platform hosting the agent may allow network access — if you need to enforce no-network behavior, verify platform/network policies; 4) if you don’t want any persistent files, avoid enabling the skill or delete ~/design-system/ after use. If the skill later requests environment variables, executables, or external URLs, treat that as a red flag and re-evaluate.

Setup

On first use, read setup.md for integration guidelines. All preferences are stored in ~/design-system/memory.md.

When to Use

User needs to create, maintain, or extend a design system. Agent handles token architecture, component patterns, documentation structure, and cross-platform consistency.

Architecture

Memory lives in ~/design-system/. See memory-template.md for structure.

~/design-system/
├── memory.md         # Status + context + decisions
└── tokens/           # Token definitions if exported

Quick Reference

Topic	File
Setup process	setup.md
Memory template	memory-template.md

Core Rules

1. Tokens First, Components Second

Design tokens are the foundation. Before building any component:

• Define color tokens (semantic, not raw hex)
• Define spacing scale (consistent multiplier)
• Define typography scale (modular)

Components consume tokens. Never hardcode values.

2. Semantic Over Literal Naming

Bad	Good
blue-500	primary
14px	text-sm
8px	space-2

Semantic names survive rebrand. Literal names break everything.

3. Three-Tier Token Architecture

Primitive → Semantic → Component
   ↓           ↓          ↓
 gray-900   text-primary  button-text

• Primitive: Raw values (colors, sizes)
• Semantic: Meaning-based (primary, danger, muted)
• Component: Specific use (button-bg, card-border)

4. Document Decisions, Not Just Specs

Every token and component needs:

• What: The value or pattern
• When: Usage context
• Why: The decision behind it
• When NOT: Anti-patterns to avoid

5. Platform-Agnostic Source of Truth

Design tokens should export to:

• CSS custom properties
• Tailwind config
• iOS/Android native
• Figma variables

One source, many outputs. Use Style Dictionary or similar.

6. Component API Consistency

All components follow the same patterns:

• Same prop naming (variant, size, disabled)
• Same size scale (sm, md, lg)
• Same variant names (primary, secondary, ghost)

Predictability beats cleverness.

7. Versioning and Migration

Breaking changes need:

• Version bump (semver)
• Migration guide
• Deprecation warnings before removal
• Codemods when possible

Common Traps

• Premature abstraction → Build 3 instances before extracting a pattern
• Token explosion → 50 grays is not a system, it is chaos
• Skipping documentation → Undocumented patterns get reimplemented wrong
• Designing for edge cases first → Cover 80% well before 100% poorly
• No dark mode strategy → Retrofit is 10x harder than planning upfront
• Inconsistent spacing → Use a scale (4px base), not arbitrary values
• Component prop sprawl → More than 10 props means split the component

Security & Privacy

Data that stays local:

• Design decisions in ~/design-system/
• Token definitions and component specs

This skill does NOT:

• Access files outside ~/design-system/
• Make network requests
• Store sensitive data

Related Skills

Install with clawhub install <slug> if user confirms:

• css — Styling fundamentals
• tailwindcss — Utility-first CSS
• frontend — Frontend development
• ui — User interface patterns
• design — Design principles

Feedback

• If useful: clawhub star design-system
• Stay updated: clawhub sync