esther-design-system

# Esther Design System > Skill by [ara.so](https://ara.so) — Design Skills collection. Esther Design System is a constraint-based design system for AI agents that transforms content into brand-consistent HTML pages. It enforces strict visual rules (colors, fonts, layouts, components) to ensure every AI-generated page looks cohesive and "not like generic AI output." ## What It Does - **Converts content → branded HTML pages** for 4 scenarios: tutorials, landing pages, apps, social media cards - **Constrains AI creativity** via predefined layouts, components, and strict brand rules - **Enforces quality** through a mandatory 7-step workflow + P0/P1/P2 checklist - **Prevents "AI look"** by banning common patterns (glassmorphism, gradients, default HTML styles) ## Core Philosophy ``` Strict constraints = consistent quality Limited options = faster decisions Explicit rules = predictable output ``` AI can only use pre-approved layouts, colors, fonts, and components. No improvisation allowed. ## Installation 1. **Clone or reference** this repository in your AI agent's context: ```bash git clone https://github.com/esthersjw/esther-design-system.git ``` 2. **Load into AI agent**: - **Cola Skill**: Place in `~/Cola/skills/esther-design-system/` - **Claude Projects**: Upload entire folder - **Cursor**: Add to workspace root and reference in `.cursorrules` 3. **Initialize workflow**: Tell your AI agent to read `SKILL.md` before any design task ## File Structure ``` esther-design-system/ ├── SKILL.md # 7-step workflow (this file) ├── brand-dna.md # Brand colors, fonts, tone, forbidden patterns ├── assets/ │ ├── template-tutorial.html # Starting point for tutorials │ ├── template-landing.html # Starting point for landing pages │ ├── template-app.html # Starting point for app UIs │ ├── template-cards.html # Starting point for social cards │ └── avatar.jpg # Brand avatar └── references/ ├── layouts.md # 15 approved layout patterns with code ├── components.md # 2988-line component library ├── checklist.md # Quality gates (P0/P1/P2) ├── scene-tutorial.md # Tutorial-specific rules ├── scene-landing.md # Landing page rules ├── scene-app.md # App UI rules └── scene-cards.md # Social card rules ``` ## 7-Step Workflow Every design task MUST follow this sequence: ### Step 1: Gather Requirements Ask the user 5 questions before starting: ``` 1. 页面类型？(tutorial/landing/app/cards) 2. 目标受众？ 3. 几屏内容？ 4. 现有素材？(文字/图片/视频) 5. 特殊约束？(截止日期/技术限制) ``` ### Step 2: Load Brand Rules Read in this order: 1. `brand-dna.md` (global rules) 2. Corresponding scene file (`scene-{type}.md`) 3. `layouts.md` (layout options) 4. `components.md` (component library) ### Step 3: Copy Base Template ```bash # Start from template, NEVER from scratch cp assets/template-{type}.html output.html ``` ### Step 4: Select 3-5 Layouts From `layouts.md`, choose layouts ensuring: - **No two sections use same layout** - Mix alignment (left/right/center) - At least one full-width section - At least one asymmetric section Example selection: ``` Section 1: Hero (Center Dominant) Section 2: Feature Grid (Offset Triple Card) Section 3: Quote (Left Text + Right Visual) Section 4: Process (Timeline Vertical) Section 5: CTA (Split Half) ``` ### Step 5: Build with Components From `components.md`, use ONLY pre-built components: ```html <!-- WRONG: Default HTML --> <blockquote>Some quote</blockquote> <!-- RIGHT: Use brand component --> <div class="quote-block-simple"> <div class="quote-line"></div> <blockquote>Some quote</blockquote> <cite>— Author</cite> </div> ``` ### Step 6: Self-Check Against Checklist Run through `checklist.md`: **P0 (Must Pass All)**: - [ ] Brand color ratio: Blue 60% / Yellow 30% / Red 10% - [ ] Zero forbidden elements (glassmorphism, neon, bounce animations) - [ ] Zero default HTML styles - [ ] Warm background (`#FFFCF5` or similar) - [ ] Serif + sans-serif mix - [ ] Responsive (mobile-first) - [ ] All sections use different layouts - [ ] Fluid sizing with `clamp()` - [ ] Doesn't look "AI-generated" **P1 (Should Pass)**: - [ ] At least one "wow" visual section - [ ] Extreme font size contrast (h1 vs body ≥ 3:1) - [ ] Scroll reveal animations - [ ] Large decorative numbers/English text ### Step 7: Deliver Output a single `.html` file that: - Opens directly in browser (no build step) - Includes all CSS inline or in `<style>` tags - Uses CDN fonts (Google Fonts, etc.) - Has no external dependencies except fonts ## Brand DNA Reference ### Colors ```css /* Primary Palette */ --brand-blue: #2B7FD8; /* 60% usage */ --brand-yellow: #F4D758; /* 30% usage */ --brand-red: #E84A5F; /* 10% usage - accents only */ /* Neutrals */ --warm-bg: #FFFCF5; --text-dark: #1A1A1A; --text-gray: #666666; /* Extension Rules */ /* OK: Tints/shades of brand colors */ --blue-light: rgba(43, 127, 216, 0.1); --yellow-bg: rgba(244, 215, 88, 0.2); /* FORBIDDEN: Purple, neon, black backgrounds */ ``` ### Fonts ```html <!-- Load in <head> --> <link href="https://fonts.googleapis.com/css2?family=Noto+Serif+SC:wght@400;700&family=Noto+Sans+SC:wght@400;500;700&family=Fraunces:ital,wght@1,400&family=Caveat&family=Fira+Code&display=swap" rel="stylesheet"> ``` ```css /* Usage */ h1, h2, h3 { font-family: 'Noto Serif SC', serif; } body, p { font-family: 'Noto Sans SC', sans-serif; } .decorative-english { font-family: 'Fraunces', serif; font-style: italic; } .handwritten { font-family: 'Caveat', cursive; } code, pre { font-family: 'Fira Code', monospace; } ``` ### Forbidden Patterns ``` ❌ Blue-purple gradients ❌ Glassmorphism (backdrop-filter: blur) ❌ Neon colors ❌ animation: bounce ❌ Inter/Roboto fonts ❌ All sections centered ❌ Default <blockquote>, <ul>, <table> styles ❌ Generic AI templates ``` ## Key Components ### Magazine-Style Card ```html <div class="card-magazine"> <div class="card-eyebrow" style="background: var(--brand-yellow);"> Category </div> <h3>Card Title</h3> <p>Description text here...</p> <a href="#" class="card-link">Learn more →</a> </div> <style> .card-magazine { background: white; padding: 2rem; border-left: 4px solid var(--brand-blue); position: relative; } .card-eyebrow { display: inline-block; padding: 0.25rem 0.75rem; font-size: 0.75rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 1rem; } </style> ``` ### Terminal Code Block ```html <div class="code-terminal"> <div class="terminal-header"> <span class="terminal-dot" style="background: #E84A5F;"></span> <span class="terminal-dot" style="background: #F4D758;"></span> <span class="terminal-dot" style="background: #2B7FD8;"></span> <span class="terminal-title">bash</span> </div> <pre><code>npm install esther-design-system</code></pre> </div> <style> .code-terminal { background: #1A1A1A; border-radius: 8px; overflow: hidden; font-family: 'Fira Code', monospace; } .terminal-header { background: #2A2A2A; padding: 0.75rem 1rem; display: flex; align-items: center; gap: 0.5rem; } .terminal-dot { width: 12px; height: 12px; border-radius: 50%; } .terminal-title { margin-left: auto; color: #999; font-size: 0.875rem; } .code-terminal pre { padding: 1.5rem; margin: 0; color: #00FF00; } </style> ``` ### Quote Block with Hand-Written Badge ```html <div class="quote-handwritten"> <span class="handwritten-badge">💡 Insight</span> <blockquote> The best design systems are the ones that constrain creativity just enough to ensure consistency. </blockquote> <cite>— Design Principle #3</cite> </div> <style> .quote-handwritten { background: rgba(244, 215, 88, 0.1); border-left: 4px solid var(--brand-yellow); padding: 2rem; position: relative; } .handwritten-badge { position: absolute; top: -0.75rem; left: 2rem; background: white; padding: 0.25rem 0.75rem; font-family: 'Caveat', cursive; font-size: 1.25rem; border: 2px solid var(--brand-yellow); transform: rotate(-2deg); } blockquote { font-size: 1.25rem; line-height: 1.6; margin: 1rem 0 0.5rem; font-style: italic; } cite { font-size: 0.875rem; color: #666; } </style> ``` ## Common Patterns ### Fluid Typography ```css /* Always use clamp() for responsive sizing */ h1 { font-size: clamp(2rem, 5vw + 1rem, 4rem); } p { font-size: clamp(1rem, 2vw + 0.5rem, 1.125rem); } ``` ### Layout Grid ```css .section-container { max-width: 1200px; margin: 0 auto; padding: clamp(2rem, 5vw, 6rem) clamp(1rem, 3vw, 2rem); } /* Three-column grid with gap */ .grid-3col { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem; } ``` ### Scroll Reveal Animation ```html <div class="reveal-on-scroll">Content</div> <style> .reveal-on-scroll { opacity: 0; transform: translateY(30px); transition: opacity 0.6s ease, transform 0.6s ease; } .reveal-on-scroll.revealed { opacity: 1; transform: translateY(0); } </style> <script> const observer = new IntersectionObserver((entries) => { entries.forEach(entry => { if (entry.isIntersecting) { entry.target.classList.add('revealed'); } }); }, { threshold: 0.1 }); document.querySelectorAll('.reveal-on-scroll').forEach(el => { observer.observe(el); }); </script> ``` ## Troubleshooting ### "Output looks too generic" - **Check**: Did you use 3+ different layouts from `layouts.md`? - **Check**: Did you include at least one decorative English/number element? - **Check**: Is there extreme font size contrast (hero vs body)? - **Fix**: Add asymmetry, use `transform: rotate()` on decorative elements ### "Colors feel off" - **Check**: Measure color usage — Blue should dominate (60%), Yellow accents (30%), Red sparingly (10%) - **Fix**: Replace overused yellow with blue tints, reserve red for CTAs only ### "Fails P0 checklist" - **Most common**: Using default `<blockquote>` or `<ul>` styles - **Fix**: Replace ALL default HTML elements with components from `components.md` - **Example**: ```html <!-- WRONG --> <ul> <li>Item 1</li> </ul> <!-- RIGHT --> <div class="custom-list"> <div class="list-item"> <span class="bullet" style="background: var(--brand-blue);"></span> <span>Item 1</span> </div> </div> ``` ### "Not responsive on mobile"