first-commit

docs/examples/DESIGN.sample.md

@@ -0,0 +1,64 @@
+# Warm Editorial
+
+> Sample DESIGN.md demonstrating the 9-section format. Used as a reference / test fixture.
+> Referenced from [`../spec.md`](../spec.md), [`../skills-protocol.md`](../skills-protocol.md), [`../modes.md`](../modes.md).
+
+## Visual Theme & Atmosphere
+Warm, unhurried, magazine-like. Think "a New Yorker interview column online." Generous whitespace, long-form readability, restrained chrome. Playful but never novelty.
+
+## Color Palette & Roles
+- **Background:** `#FAF7F2` (warm off-white paper)
+- **Foreground:** `#1C1A17` (near-black, slightly warm)
+- **Accent (primary):** `#C0512F` (terracotta) — used for links, primary CTAs, 1 hero element max per page
+- **Accent (secondary):** `#2F5B4F` (forest) — section dividers, tags
+- **Muted:** `#8A817A` (mid-warm-grey) — timestamps, metadata
+- **Surface:** `#FFFFFF` — elevated cards only
+Never use pure black or pure white anywhere user-facing.
+
+## Typography Rules
+- **Display / headings:** "GT Sectra" or fallback serif (`'GT Sectra', 'Times New Roman', serif`)
+- **Body:** "Söhne" or fallback sans (`'Söhne', -apple-system, system-ui, sans-serif`)
+- **Mono:** `'JetBrains Mono', ui-monospace, monospace` for code only
+- Scale (px): 12 · 14 · 16 · 20 · 28 · 40 · 56 · 80
+- Line-height: 1.6 for body, 1.2 for display
+- Letter-spacing: -0.02em for display sizes above 40px; default elsewhere
+
+## Component Stylings
+- **Buttons:** flat fill, 12px radius, 14px padding-block, 20px padding-inline. Primary = terracotta fill, off-white label. Secondary = outlined 1px foreground, transparent fill.
+- **Cards:** off-white background, 1px forest-at-8%-opacity border, 16px radius, 24–32px internal padding. No shadow except hover (y+2px, blur 16, foreground-at-6%).
+- **Inputs:** underline only (no box), 1px muted baseline, terracotta baseline on focus, 16px vertical padding.
+- **Links:** terracotta, 1px terracotta-at-40% underline, no underline on hover (swap for terracotta-at-8% background).
+
+## Layout Principles
+- 12-column grid, 1200px max-width, 24px gutters.
+- Hero sections: 72vh minimum, 120vh maximum. Content top-biased, never centered vertically.
+- Body sections: 80px top+bottom spacing at desktop; 48px at tablet; 32px at phone.
+- One accent color per screen. If a page has a terracotta hero, secondary CTAs are foreground-only, not forest.
+
+## Depth & Elevation
+Minimal. Only two elevation levels:
+- **Flat (0):** everything by default.
+- **Raised (1):** cards on hover, dropdown menus, floating CTAs. 2px y-offset, 16px blur, foreground at 6% opacity.
+No shadows on inputs. No shadows on the hero. No neumorphism, no glassmorphism.
+
+## Do's and Don'ts
+- ✅ Let whitespace breathe. A short headline on 50% of the viewport height is correct.
+- ✅ Use serif for numbers when they matter (pricing, stats).
+- ✅ Draw one accent element per page; the rest is foreground.
+- ❌ No gradients.
+- ❌ No emojis in product copy.
+- ❌ No sentence-case for headings — use title case for H1/H2, sentence case for H3 and below.
+- ❌ No border-radius above 24px; no border-radius below 8px.
+
+## Responsive Behavior
+- **Desktop ≥ 1024px:** 12-col grid, full hero heights, side-by-side columns.
+- **Tablet 640–1023px:** 8-col grid; hero drops to 60vh; columns stack at 3+.
+- **Phone < 640px:** 4-col grid; single-column layout; hero drops to 50vh; all padding -33%.
+
+## Agent Prompt Guide
+When generating artifacts against this design system:
+- Lead with typography and whitespace; chrome (borders, shadows) is subtractive.
+- If you need more than one accent element on a screen, you're doing too much — cut one.
+- When asked for "professional" or "serious," lean harder on serif + whitespace. When asked for "modern," this system isn't the right answer; pick a different DESIGN.md.
+- Color tokens are non-negotiable. Do not invent new hex values. If the request needs a color outside this palette, produce a warning comment in the artifact and use the closest existing token.
+- Prefer 1 hero + 3–5 body sections over 1 hero + 8+ sections. Editorial means restraint.

docs/examples/saas-landing-skill/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: saas-landing
+description: |
+  Single-page SaaS landing with hero, features, social proof, pricing, and CTA.
+  Respects the active DESIGN.md color/typography/layout tokens.
+  Trigger keywords: "saas landing", "marketing page", "product landing".
+triggers:
+  - "saas landing"
+  - "marketing page"
+  - "product landing"
+od:
+  mode: prototype
+  preview:
+    type: html
+    entry: index.html
+    reload: debounce-100
+  design_system:
+    requires: true
+    sections: [color, typography, layout, components]
+  inputs:
+    - name: product_name
+      type: string
+      required: true
+    - name: tagline
+      type: string
+      required: true
+    - name: has_pricing
+      type: boolean
+      default: true
+    - name: proof_count
+      type: integer
+      default: 3
+      min: 0
+      max: 6
+  parameters:
+    - name: hero_density
+      type: spacing
+      default: 96
+      range: [48, 200]
+    - name: accent_strength
+      type: opacity
+      default: 1.0
+      range: [0.5, 1.0]
+  outputs:
+    primary: index.html
+  capabilities_required:
+    - file_write
+---
+
+# SaaS Landing Skill
+
+Produce a single-page SaaS landing. Agent, follow this workflow exactly.
+
+## 1. Read context
+
+Before writing anything:
+- Read `DESIGN.md` in the current working directory. If missing, stop and ask for one.
+- Identify the color palette, typography tokens, and layout principles.
+- Note the "Agent Prompt Guide" section — it overrides any instruction here if they conflict.
+
+## 2. Plan sections
+
+Required sections, in order:
+1. **Hero** — logo-or-wordmark, headline (tagline input), subhead (1–2 sentences), primary CTA, secondary CTA. Use the hero_density parameter as vertical padding in px.
+2. **Features** — 3–6 feature tiles. Each: icon, short title, 1–2 sentence body.
+3. **Social proof** — `proof_count` logos or testimonials. If 0, skip this section.
+4. **Pricing** — 2–3 tiers. Include only if `has_pricing` is true.
+5. **Footer CTA** — large accent-colored band with one-button call to action.
+6. **Footer** — minimal: links + copyright.
+
+## 3. Apply design system
+
+- All colors must come from DESIGN.md tokens. Do not invent hex values.
+- Typography: use the declared display font for headlines, body font for everything else.
+- Layout: respect the grid, max-width, and section spacing rules.
+- Components: use declared button/card/input patterns. Do not add shadows if DESIGN.md's Depth & Elevation says minimal.
+- Accent: use the accent color only once in the hero, once in the footer CTA, and for all links. Do not flood the page.
+
+## 4. Write the file
+
+Output a single self-contained `index.html` with:
+- All CSS inlined in a `<style>` block in `<head>`.
+- System font fallbacks if DESIGN.md fonts aren't loadable from Google Fonts etc.
+- No external JS.
+- Semantic HTML (`<header>`, `<main>`, `<section>`, `<footer>`).
+- Each editable element tagged with `data-od-id="<unique-slug>"` so the host app's comment mode can target it.
+
+## 5. Self-check
+
+Before finishing, verify:
+- [ ] All text is content-meaningful, not lorem ipsum (use product_name and tagline inputs; generate plausible specific copy for the rest).
+- [ ] No broken color references (every CSS color value is in DESIGN.md's palette or a valid alpha/fallback variant).
+- [ ] Responsive breakpoints match DESIGN.md's Responsive Behavior section.
+- [ ] The page looks good at 1440w, 768w, and 375w (mentally simulate).
+- [ ] Accent used no more than twice total.
+
+## 6. Done
+
+Write only `index.html`. Do not generate a separate CSS file, JS file, or README.
+
+---
+
+## For skill authors reading this as a reference
+
+This is a minimal but complete skill. Structure:
+
+```
+saas-landing-skill/
+├── SKILL.md    ← you are here
+└── assets/
+    └── base.html    (optional starter template; this skill doesn't use one)
+```
+
+Things to notice:
+- The `od:` front-matter block is optional for Claude-Code-only compatibility, but adding it lights up OD's typed inputs, sliders, preview metadata, and capability gating.
+- The workflow below the front-matter is plain Markdown that the agent reads as its system prompt.
+- DESIGN.md is treated as a collaborator, not an override. The skill gives the agent authority to override when the brief conflicts, but never to invent new tokens.
+- `data-od-id` tagging is how we wire elements to comment mode. Skills that want comment-mode compatibility must annotate their output.
+
+See [`../../skills-protocol.md`](../../skills-protocol.md) for the full protocol.