Skema

Skema — Master Orchestrator

This file is the entry point. The active coding agent reads this FIRST on every Skema invocation. Every rule here is binding. No interpretation. No deviation.

1. What Skema Is

Skema is the single design skill for compatible coding agents. It produces:

• Full design systems (tokens, components, interactive preview, Figma-ready)
• Multi-screen canvases (Figma-style side-by-side mockups)
• Clickable prototypes (real navigation, Playwright-verified)
• Animations (HTML → MP4/GIF export, BGM, 60fps)
• AI-to-AI handoff packages (HANDOFF.md + tokens + screens + components)
• Codebase-aware redesigns (reads existing stack, extends it, never alien)
• URL-cloned design systems (extract → reverse-engineer → tokenize)
• Figma bidirectional sync (pull tokens/components, push generated systems)
• Image-to-code (screenshot → production component matching existing codebase)
• Scored critique (8-dimension review, blocks handoff below 7.0)

It is general-purpose. It incorporates the principles normally reached for in impeccable, high-end-visual-design, image-to-code, minimalist-ui, redesign-existing-projects, design-taste-frontend, emil-design-eng, and frontend-design. Do not invoke other design skills unless the host agent explicitly requires it or the user asks.

2. Trigger Surface — When To Activate

Slash commands (exact match → activate immediately)

Primary commands: /skema <subcommand>. Backward-compat aliases: /design <subcommand> and /design-engine <subcommand> work identically.

Natural-language triggers (case-insensitive substring match → activate)

design this              redesign                  create UI
build interface          clone [url]               design system
component library        create prototype          hi-fi
hi fi                    high fidelity             mockup
mock up                  canvas                    design tokens
figma sync               figma push                figma pull
review this design       critique                  handoff
make this look better    polish this UI            ship-quality design
landing page             dashboard                 onboarding flow
auth screen              settings page             pricing page
screenshot to code       image to code             extract design system

If the user's message contains a trigger AND describes visual/UI work → activate. Ambiguous cases (e.g. "fix this CSS bug") are NOT triggers — that is a code task, not a design task. When in doubt, ask one clarifying question instead of assuming.

Anti-triggers — DO NOT activate

• Pure backend, API, database, or infrastructure work
• Bug fixes that don't touch visual output
• Refactors that preserve the existing UI
• Documentation tasks unrelated to design

3. Core Philosophy — Binding Rules

Rule 1 — Design System First

Every output derives from a design system. Pipeline is fixed:

Brief → Context Intake → Design System → Components → Output

Never skip steps. Never generate a screen before the system exists. Never hardcode values in a screen. Every value references a token.

Rule 2 — Read Before Generate

Before generating ANY pixel, the skill MUST:

1. Scan the current codebase (if inside a project)
2. Fetch any URL the user references when network/tools are available
3. Analyze any screenshot the user attached
4. Run web research relevant to the task when network/tools are available

Generating blind produces AI slop. If network or browser tools are unavailable, continue using provided context and state that research was skipped.

Rule 3 — Safe Zone Only

All generated output goes to .skema/ relative to the current working directory. In daemon/UI mode, the current working directory is already the project workspace (for example .skema/projects/<id>/), so generated files belong under that workspace's .skema/.

NEVER write to src/, app/, components/, pages/, public/, or any existing production directory. Promotion to production is the user's manual action via explicit cp commands shown in the terminal output.

Rule 4 — Handoff Is The Product

The deliverable is .skema/handoff/HANDOFF.md plus its bundle. Every flow ends with a handoff package the user can copy-paste into Claude Code, Codex, Cursor, or another compatible coding agent with zero ambiguity.

Rule 5 — One Distinctive Detail

Every screen ships with one screenshottable moment — a single, intentional, non-default detail (a custom interaction, an unexpected typographic choice, a meaningful animation, a deliberate density). Without it the output is mediocre. With more than two it is noise.

Rule 6 — Complete HTML Files

Every HTML file created by Skema must be a complete self-contained document. Never write placeholder text like "See index.html" to any file. Each screen gets its own full HTML document.

4. Output Modes — Canvas / Prototype / Both

Always ask first (after brief is confirmed, before generation)

Output mode?
  [C] Canvas     → Figma-style layout, all screens side by side, annotations
  [P] Prototype  → Fully clickable, real navigation, Playwright-verified
  [B] Both       → Canvas first → approve → Prototype built from it (default)

Skip the prompt only if

• The slash command implies the mode (/skema system → system preview, no canvas/proto)
• The user already specified mode in their message ("build a clickable prototype")
• The user has a .skema.json with "mode" set

In Both mode (default)

1. Generate canvas
2. STOP. Show user. Ask: "Approve canvas? (Mark sections Looks good / Needs work)"
3. Only after explicit approval → generate prototype from approved canvas
4. Never build prototype before canvas approval

5. Pipeline Order — Fixed Sequence

The router (modules/00-router.md) selects modules. The sequence below is the canonical order. Modules may be skipped when irrelevant; their relative order is never reordered.

0. modules/00-install-hook.md      ← first-run only, when host supports hooks
1. modules/00-router.md            ← parse intent, choose path
2. modules/01-context-intake.md    ← fuse text/visual/code/figma context
3. modules/04-codebase-scan.md     ← if inside a project
4. modules/03-clone-engine.md      ← if URL clone requested
5. modules/12-image-to-code.md     ← if screenshot provided
6. modules/05-web-research.md      ← competitor + trend + reference research, if tools available
7. modules/02-design-interview.md  ← gap-based, max 4 questions
8. modules/06-system-selection.md  ← only for /skema system
9. modules/13-figma-pull.md        ← only for /skema import
10. modules/07-design-system-gen.md ← always, before any screen
11. modules/08-component-library.md ← generate components from tokens
12. modules/09-canvas-mode.md       ← if mode includes Canvas
13. modules/10-prototype-mode.md    ← if mode includes Prototype (after canvas approval)
14. modules/11-animation.md         ← only when animation requested
15. modules/14-figma-push.md        ← if user asked to push to Figma
16. modules/15-critique.md          ← always, before handoff
17. modules/16-handoff.md           ← always, the final step

Routing decision table (used by 00-router.md)

6. Hardcoded Anti-Slop Rules — NON-NEGOTIABLE

These rules apply to every output. Violating any of them is a defect. Critique (15) flags violations and blocks handoff if any are present.

NEVER generate

• Purple/blue gradients as hero or card backgrounds
• Rounded cards with a left-side colored border accent
• Sans-serif everywhere with no display personality
• Default Heroicons at default size and stroke weight
• AI blue (#6366f1, #8b5cf6) as primary unless explicitly requested
• max-w-2xl centered everything layout
• Glassmorphism without a clear purpose
• Fake 3D elements that don't commit to the illusion
• Emoji as UI icons
• Stock-photo aesthetics
• More than 3 different font sizes on one screen
• More than 2 font weights in one visual group
• Shadows in dark mode (use border elevation instead)
• Hardcoded color values in generated code (always token references)
• Box-shadow transitions on hover (use transform instead)
• Lorem ipsum in prototypes — use realistic data
• Tailwind arbitrary values when a token exists
• Inline styles on production components
• outline: none without a replacement focus indicator
• Annotation overlays, callout boxes, tooltip badges, label overlays, off-token chips, component name pills, or any explanatory text rendered on top of canvas or prototype screens. Annotations are OFF by default. When --annotate is on, annotations live in a strip BELOW the screen frame (module 09 §5.1), NOT on top of the design. The screen at all times must be fully visible and unobstructed. Spacing redlines require the explicit --annotate --redlines combination and render as a translucent toggleable layer; they are the only exception to "annotations never on screen", and they default to off even within that mode. See module 09 §0 Clean Canvas Rule.
• Placeholder HTML files that point to another file instead of containing the actual screen.

ALWAYS generate

• oklch() for every color value
• 4-dimension typographic hierarchy (size, weight, color, spacing)
• One unexpected/distinctive detail per screen (the screenshottable moment)
• Hover states on all interactive elements
• Focus rings on all focusable elements
• Negative letter-spacing on text above 20px
• GPU-composited animations only (transform + opacity)
• Token references in all code
• Dark mode consideration for every component
• Real content (real names, real numbers, real copy) in prototypes
• Min 44×44px touch targets on mobile
• WCAG AA contrast minimum (AAA preferred where readable)
• Complete self-contained HTML for every generated .html screen

7. Safe Zone — File System Contract

NEVER write to (production code zone)

src/          app/          components/    pages/
public/       styles/       lib/           hooks/
utils/        api/          server/        prisma/
any file at the project root except .skema.json

Writing to any of the above is a hard violation. If a generated file needs to live there eventually, output it to .skema/handoff/ and instruct the user to copy it manually.

ALWAYS write to (safe zone)

Paths below are relative to the current working directory.

.skema/
├── system/                  ← active design system
│   ├── tokens.json
│   ├── tokens.css
│   ├── tokens.ts
│   ├── tokens.tailwind.js
│   ├── tokens.figma.json
│   ├── system-preview.html  ← self-contained interactive preview
│   ├── SYSTEM.md
│   └── components/
├── canvas/[timestamp]/      ← canvas mode outputs
├── prototype/[timestamp]/   ← prototype outputs
└── handoff/                 ← final handoff package
    ├── HANDOFF.md
    ├── design-tokens.{json,css,ts,tailwind.js}
    ├── screens/
    ├── components/
    └── assets/

Committed config

.skema.json at project root — the ONE file Skema writes outside .skema/. Schema:

{
  "system": "saas-dark",
  "version": "1.0.0",
  "adapted": true,
  "stack": "nextjs-tailwind-shadcn",
  "mode": "both",
  "figmaFileKey": null,
  "lastSync": null
}

Gitignore

On first run, ensure .skema/ is in .gitignore. If .gitignore doesn't exist, create it with .skema/ as the only line. If it exists and the entry is missing, append. Never modify other gitignore lines.

8. Module Reference Index

Every module is loaded on demand by the router. Paths are relative to the skill root.

Reference docs (load on demand)

Pre-built systems (12, load only the selected one)

systems/{linear,vercel,stripe,raycast,notion,saas-light,saas-dark,
         mobile-ios,mobile-material,editorial,minimal,enterprise}/

Each system contains: tokens.{json,css,ts,tailwind.js,figma.json}, system.md, preview.html, components/{button,card,input,nav,table, badge,modal,toast}.jsx.

Assets

assets/frames/{iphone-15-pro,android,browser,macos-window,desktop}.html
assets/animation-engine/{animations.jsx,deck-stage.js}
assets/component-starters/design-canvas.jsx

9. Agent Compatibility

Skema must work across Claude Code, Codex, Cursor, and compatible coding agents.

• Claude Code: supports native slash skill loading and may support hooks/settings.
• Codex: frontmatter description must remain under 1024 characters. Hooks or MCP integrations may be unavailable. Continue without hook installation if unsupported.
• Cursor: hooks/settings may differ. Do not fail if unavailable.
• Other agents: follow the filesystem/output contract; skip unsupported integrations and state what was skipped.

Host-specific setup must never block the design pipeline unless the missing capability is essential to the user's requested output.

10. Operating Sequence — Every Invocation

The agent MUST follow this sequence on every Skema activation. No step is optional unless explicitly marked.

0. Run install-hook when supported. First action on every invocation when the current host supports local hooks/settings. Read modules/00-install-hook.md and execute it. The module owns its own idempotency: it checks .skema.json, ~/.claude/settings.json, and ~/.cursor/settings.json where present, and exits silently when already installed. If the current host does not expose compatible hook/settings files, skip silently and continue.
1. Parse trigger. Identify slash command or natural-language trigger. Confirm this is a design task (not a code/backend task).
2. Load router. Read modules/00-router.md. Use its decision table.
3. Load context. Read modules/01-context-intake.md. Gather every provided source: text, screenshots, URLs, code, Figma links.
4. Scan codebase. If inside a git repo with frontend code, run modules/04-codebase-scan.md. Display the Codebase Design Snapshot.
5. Run sub-pipelines. If URL given → clone-engine. If screenshot → image-to-code. If Figma URL → figma-pull. Run in parallel where possible.
6. Web research. Run modules/05-web-research.md when network/browser tools are available unless the brief is so concrete that research adds nothing. If unavailable, continue using provided context and state that research was skipped.
7. Interview. Run modules/02-design-interview.md. Max 4 questions. Skip questions whose answers are already in context.
8. Confirm brief. Display the Design Brief Summary block. WAIT for the user to confirm or adjust before generating anything.
9. Ask output mode. Show Canvas/Prototype/Both prompt unless resolved (see §4). WAIT for selection.
10. Generate system. Run modules/07-design-system-gen.md. Write to .skema/system/. Show preview path.
11. Generate components. Run modules/08-component-library.md.
12. Generate canvas / prototype. Run modules 09 and/or 10. In Both mode, generate canvas first, WAIT for approval, then prototype.
13. Critique. Run modules/15-critique.md. Display 8-dimension scores. If overall < 7.0, fix issues and re-run before handoff.
14. Handoff. Run modules/16-handoff.md. Display the terminal output block with promote instructions and scores.

Stop conditions

• User says "stop", "cancel", "wait" → halt immediately, do not generate.
• Brief unconfirmed → do not proceed past step 8.
• Output mode unselected → do not proceed past step 9.
• Canvas not approved (Both mode) → do not generate prototype.
• Critique < 7.0 and fixes exhausted → present scores, do not bundle handoff.

11. Communication Contract

Always show

• Codebase Design Snapshot (after step 4)
• Research Brief (after step 6, optional, condense if long)
• Design Brief Summary (step 8) — REQUIRES user confirmation
• Output mode prompt (step 9) — REQUIRES user selection
• Canvas approval prompt (step 12, Both mode) — REQUIRES user approval
• Critique scores (step 13)
• Final handoff terminal block (step 14)

Never show

• Internal module content verbatim
• Token JSON dumps in chat (link to file instead)
• Long explanations during generation (keep status terse)

Tone

Terse, declarative, technical. No filler. Match the user's register. Code/commits/file content: write normally. The agent's chat output itself should be dense and direct.

11.5 UI Mode (structured JSON output)

When the environment variable SKEMA_UI_MODE=true is set, emit Skema pipeline events as newline-delimited JSON (NDJSON). Each Skema event line must be a single complete valid JSON object with a type field.

Activation: SKEMA_UI_MODE=true environment variable.

Effect: Skema-controlled stdout should be NDJSON event lines. Some host agents may still emit tool/status noise, warnings, or wrapper text. Keep Skema event lines valid and self-contained so UI clients can parse JSON lines and ignore non-JSON lines.

Terminal mode: unchanged when the env var is unset.

UI clients consume the stream by reading line-by-line, JSON-parsing valid JSON lines, and ignoring non-JSON host noise. Modules document their events in their own files (modules/00-router.md emits pipeline_start first, then each module emits its own events as it runs).

Top-level event types

pipeline_start, pipeline_complete
intake_start, intake_complete
question, question_answered, interview_complete, brief_confirmed
research_start, research_update, research_complete
system_selection_prompt, system_selected, blend_decisions
todo_update
file_ready
canvas_approval_needed
playwright_result
critique_ready
handoff_ready
migration_complete
reference_loaded
inspect_complete
figma_local_start, figma_local_complete

Each event's full schema is documented in the emitting module.

Terminal mode contract: when the env var is not set, output behaves exactly as documented in §11. No JSON requirement. No structural difference.

12. Conflict Resolution

If the user's instruction conflicts with a rule in this file:

1. Anti-slop rules (§6) — never overridden. State the rule, refuse the conflicting instruction, propose a compliant alternative.
2. Safe zone rules (§7) — never overridden. Ever.
3. Pipeline order (§5) — may be shortened (skip irrelevant modules) but never reordered.
4. Output mode and brief confirmation — may be skipped only if the user has explicitly opted out ("just generate it, skip the questions").
5. Everything else — defer to the user.

If two rules in this file appear to conflict, the earlier-numbered section wins.

13. First-Run Setup

On first invocation in a project, before the router runs:

0. Run modules/00-install-hook.md when supported — installs the silent auto-update hook into ~/.claude/settings.json and, if detected, ~/.cursor/settings.json. Idempotent and non-destructive: existing hooks are never overwritten; if the Bil0000/skema-skill hook is already present, the module exits silently. Records hookInstalled: true in .skema.json. If the host agent does not support these settings files, skip this setup step silently and continue.
1. Create .skema/ directory.
2. Append .skema/ to .gitignore (create file if missing).
3. Create .skema.json with defaults filled from codebase scan. Merge with whatever 00-install-hook.md already wrote.
4. Inform the user once: "Initialized .skema/ — committed config: .skema.json, working files: .skema/ (gitignored)."

Do not repeat the init message on subsequent runs. The install-hook module has its own per-target detection and will re-run on demand via /skema install-hook --recheck.

End of orchestrator. Router is next: modules/00-router.md.