elementary
Skill2 starsChanged 49 days agoMITView on GitHub
Token-based design system with standardized CSS custom property names, multiple theme implementations (polished with light/dark mode, sketch), and optional component patterns. Use with reactive-md and React frameworks such as Next.js, Remix, or Vite for themeable interfaces, design system compliance, or switching between visual fidelity levels without code changes.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- reactive-mdSkill
- takeover-from-claudeSkill
- test-auditSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 287
Read references/token-system.md - Complete token taxonomy
- Very specific: line 292
Read references/themes.md - All available themes
- Very specific: line 297
Read references/components.md - All available classes
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Elementary Design System
Elementary is a design system comprised of three independent, orthogonal layers:
Layer 1: Token Naming System
- Standardized names (
--c-primary,--s-4, ...) - The unchanging contract
- Used across ALL themes
Layer 2: Theme Implementations
- Different VALUES for the same names
- Currently: polished, sketch
- Future: custom themes, brand themes
Layer 3: Component Classes
- Optional pre-built patterns
- Uses Layer 1 token names
- Works with ANY Layer 2 theme
Key Insight: Token NAMES stay constant across themes; only token VALUES change. This allows switching visual fidelity by changing a single CSS import without touching Layer 1 (token names) or Layer 3 (component code).
When to Use This Skill
Token-Based Styling:
- Design system approach with reusable tokens
- Consistent spacing, colors, and typography across projects
- Themeable interfaces (light/dark mode, fidelity levels)
Visual Fidelity Control:
- High-fidelity prototypes (polished, production-ready)
- Low-fidelity wireframes (structural mockups)
- Switch between fidelity levels without code changes
Component Consistency:
- Pre-built component patterns for rapid prototyping
- Design system compliance
Keywords: Elementary, design tokens, CSS variables, light/dark mode, themeable, high-fidelity, sketch, component classes (wf-btn, wf-card), design system
Not a Fit For: Utility-first styling (use Tailwind), quick prototypes without design system constraints, fully custom styling without reusable patterns
Quick Start
Import a Theme
/* Polished (production-ready with light/dark mode) */
@import './assets/elementary/tokens/polished.css';
@import './assets/elementary/components.css'; /* optional */See: references/themes.md for complete theme documentation
Installing Elementary Assets
To use Elementary in your own project, install the assets locally:
# From your project directory
/path/to/elementary/scripts/elementary.mjs install .This creates assets/elementary/ in your project with the same structure as this skill.
Component Classes First, Tokens for Custom Components
Primary Approach: Use Component Classes
<article className="wf-card">
<h3 className="title">Card Title</h3>
<p className="description">Card content</p>
</article>Tiny Tweaks: Inline Style Overrides (1-2 properties only):
<article className="wf-card" style={{
backgroundColor: 'var(--c-slate-100)' /* Single override OK */
}}>
<h3 className="title">Card with custom background</h3>
<p className="description">Override theme for quick escape</p>
</article>Custom Components: Use Tokens in CSS (when no component class exists):
/* Import Elementary tokens first */
@import './assets/elementary/tokens/polished.css';
/* Create your own class when `components.css` doesn't have what you need */
.custom-alert {
padding: var(--s-4);
border-radius: var(--r-card);
background-color: var(--bg-surface);
border-left: 4px solid var(--c-primary);
color: var(--c-text);
& .title {
font: var(--t-heading);
}
}<article className="custom-alert">
<h3 className="title">Custom Alert</h3>
<p>This component doesn't exist in components.css,
so we created a CSS class using Elementary tokens.
</p>
</article>Rule: Component classes → Tiny inline tweaks (1-2 properties) → Custom CSS classes with tokens. Never extensive inline styles.
See: references/components.md for all available component classes
Core Concepts
Layer 1: Token Naming System (The Contract)
Standardized names used across ALL themes:
--c-primary,--c-secondary(colors)--bg-surface,--bg-overlay(backgrounds)--s-4,--s-6(spacing: 16px, 24px)--r-btn,--r-card(radius)
Token Hierarchy:
- Primitives: Raw scales (
--s-4,--c-slate-500) - use in theme files - Semantics: Intent-based (
--c-primary,--bg-surface) - use in CSS classes for custom components
When to Use Design Tokens:
- Creating custom CSS classes for components not in component-library.css
- Building your own design system on top of Elementary
- Tiny inline overrides (1-2 properties max)
When NOT to Use Design Tokens:
- Component classes already exist (use wf-btn, wf-card, etc.)
- Would result in >2 inline style properties (create a CSS class instead)
See: references/token-system.md for complete token taxonomy
Layer 2: Theme Implementations (The Values)
Different VALUE assignments to the same token NAMES:
Polished:
- Semantic colors with light/dark mode
- Professional typography
- Refined shadows
- Production-ready
Sketch:
- Grayscale palette
- Monospace typography
- Minimal shadows
- Structural focus
Theme Switching: Change import path only - all code remains unchanged.
See: references/themes.md for theme characteristics and usage
Layer 3: Component Classes (Optional Patterns)
Pre-built patterns in assets/components.css:
.wf-btn,.wf-card,.wf-hero(UI components).title,.description,.actions(semantic children)- Works with ANY Layer 2 theme
See: references/components.md for all available components
Critical Rules
✅ DO
Use Component Classes First:
<div className="wf-card">
<button className="wf-btn primary">Use Tokens in CSS Classes (for custom components):
.my-custom-alert {
color: var(--c-primary);
background-color: var(--bg-surface);
padding: var(--s-4);
}Inline Overrides for Tiny Tweaks (1-2 properties max):
<div className="wf-card" style={{ backgroundColor: 'var(--c-accent)' }}>Change Themes via Import:
/* Switch from polished to sketch */
@import './assets/elementary/tokens/sketch.css';❌ DON'T
Mix Tailwind with Elementary:
{/* WRONG */}
<div className="wf-card p-4 flex gap-2">Invent Component Classes:
{/* WRONG - .wf-dashboard-card doesn't exist */}
<div className="wf-dashboard-card">Use Primitive Tokens in Component Code:
/* WRONG - use semantics instead */
color: var(--c-slate-700);Hardcode Values:
/* WRONG - defeats the token system */
padding: 16px;
color: #333333;Excessive Inline Styles (>2 properties):
{/* WRONG - code smell, create a CSS class instead */}
<div style={{
padding: 'var(--s-6)',
borderRadius: 'var(--r-card)',
backgroundColor: 'var(--bg-surface)',
border: '1px solid var(--c-border)'
}}>Light/Dark Mode (Polished Theme Only)
Polished theme uses light-dark() CSS function for automatic theming:
User Control:
// Toggle theme
document.documentElement.style.colorScheme = 'dark'; // or 'light'System Preference (Automatic):
/* Already set in polished.css */
:root { color-scheme: light dark; }Note: Sketch theme does not support light/dark mode (intentionally grayscale).
See: references/themes.md for browser compatibility and fallbacks
Cross-Skill Composition
Elementary works standalone OR composed with other skills:
With reactive-md:
/* From reactive-md document */
@import './assets/elementary/tokens/polished.css';
@import './assets/elementary/components.css';With React frameworks:
/* Next.js, Remix, Vite - adjust relative path as needed */
@import './assets/elementary/tokens/polished.css';Discovering Resources
Token Names (Layer 1):
- Read
references/token-system.md- Complete token taxonomy - Semantic vs primitive hierarchy
- "Ink & Paper" metaphor
Theme Values (Layer 2):
- Read
references/themes.md- All available themes - Polished vs sketch characteristics
- Light/dark mode implementation
Component Classes (Layer 3):
- Read
references/components.md- All available classes - Semantic child elements
- Component-level token patterns
Usage Examples:
references/recipes/- Common patterns (buttons, cards, dashboards, landing pages, settings pages)
Installation Tool:
# Install Elementary assets to current directory
/path/to/elementary/scripts/elementary.mjs install .Discovery Tool (if available):
// Discover component classes and tokens
list_design_classes({
css_file: "assets/elementary/components.css",
include_tokens: true,
theme: "polished"
})Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

