# StyleSeed — design method for any coding agent

This is the cross-agent entry point for Codex, Amp, Gemini CLI, Windsurf, Cline, and other
tools that read `AGENTS.md`. Claude Code uses `CLAUDE.md`; Cursor uses `.cursorrules`.

StyleSeed fixes **how an agent judges design**, not one Toss-like aesthetic. It applies to web
and mobile products, social carousels, slide decks, documents/reports, and single-frame graphics.

## Resolve only the context this artifact needs

Invoke `$ss-resolve` from `STYLESEED.md`, then read `.styleseed/effective-rules.md` and keep
`.styleseed/manifest.json`. The deterministic resolver composes core → grammar → adapter →
domain/page → brand recipe → optional profile → lock → craft baseline and records source hashes. Do not load
`llms-full.txt` after a bundle resolves successfully.

Use `$ss-resolve --list` when selecting IDs. Open the full source handbook only when the
compiled bundle identifies a genuine ambiguity. See `ARCHITECTURE.md` for the full system.

## Composition model

```text
core judgment
× output grammar (built-in or reference-compiled)
× surface adapter
× domain + page/artifact type
× brand recipe (morphology + component selection)
× optional aesthetic profile
× bounded STYLESEED.md values
= effective rules for the artifact
```

Toss is evidence for `consumer-service`, not the StyleSeed default. Aesthetic profiles such as
`swiss` or `technical` coordinate appearance; they do not replace functional output grammar.
Brand recipes such as `enterprise-workbench` or `editorial-authority` change geometry,
containment, controls, and collection patterns without cloning the companies in their lineage.

## Core invariants

- One coherent system for radius, spacing, elevation, type, icons, color roles, imagery, and motion.
- One focal point and one identifiable primary action.
- Additional color requires a stable semantic, categorical, editorial, data, or brand role.
- Semantic tokens replace component-local hardcoded colors.
- Spacing and proximity create repeatable grouping.
- Typography fits the task, surface, reading distance, and content measure.
- Data surfaces have useful loading, empty, and error states.
- Focus, contrast, targets, labels, reduced motion, and honest consent remain intact.
- Motion fits the artifact and never delays comprehension or action.
- Distinctiveness comes from product content and the selected grammar, never copied demos,
  generic indigo, repeated icon chips, emoji chrome, or template uniformity.

The design lock persists valid selections. It cannot waive these invariants or invent a new
palette mode.

## Design lock — read before every visual task

Look for `STYLESEED.md` in the project root. If missing, use setup before writing visual code or
render scripts. A valid lock resembles:

```markdown
# StyleSeed — Design Lock
<!-- Persistent selections. This file cannot waive core invariants. -->
- App domain: fintech
- Surface: mobile-app
- Surface adapter: product-ui
- Page type: dashboard
- Output grammar: consumer-service
- Grammar path: built-in:engine/RULESETS.md
- Grammar fallback: consumer-service
- Reference confidence: n/a
- Brand recipe: calm-consumer
- Aesthetic profile: none
- Skin: custom
- Primary action: #3182F6
- Font: Pretendard
- Radius: soft
- Elevation: light=tonal grouping + restrained shadow · dark=tonal ramp + hairline
- Density: comfortable
- Motion: Spring restrained
- Imagery/data role: personal state first; charts only for a decision
- Signature move: one calm contextual briefing above the account summary
- Locked: YYYY-MM-DD
```

For non-web output add adapter fields such as canvas, artifact type, renderer, and safe-zone
contract. Unknown values are resolver errors; they are not exemptions.

## Setup and reference routing

1. Understand the user, job, domain, artifact, platform, and primary decision.
2. Use `$ss-resolve --list` to select one output grammar and one adapter.
3. If supplied references are not represented, use `$ss-reference` and
   `REFERENCE-COMPILER.md`. Never reduce a reference to a palette swap or clone its protected
   assets, text, or trademarked arrangement.
4. Select one brand recipe from `BRAND-RECIPES.md`; use `auto` only when its grammar mapping fits.
5. Select domain/page bias and at most one optional aesthetic profile.
6. Confirm bounded brand/type/density/radius/elevation/imagery/motion values, write the lock,
   then run `$ss-resolve` and read the effective bundle before implementation.

Reference compilation produces evidence, confidence, tokens, anti-patterns, adapter metadata,
and a transfer validation artifact under `.styleseed/rulesets/<slug>/`.

## Build loop

Use `$ss-build` when installed:

```text
select or compile grammar → select adapter → lock → build with the composed method
→ $ss-score → fix to >=80 → render → $ss-verify → fix and re-render → present evidence
```

The build method is the product. Score and verification are auxiliary proof gates.

### Code gate

`$ss-score` reads implementation evidence and names the effective rule set. It checks eight
weighted categories: color, hierarchy/type, layout/rhythm, surfaces/elevation, states/a11y,
motion/interaction, coherence, and distinctiveness. Fix highest-gain failures and re-score.

### Pixel gate

For every renderable artifact, `$ss-verify` must inspect actual output at the adapter's required
viewports, frames, pages, and states. Check focal dominance, loaded type, balance, optical rhythm,
crop/safe zones, contrast, responsive transformation, and grammar fit. Re-render after fixes.
Never claim a visual pass without seeing the rendered artifact.

For example, StyleSeed supplies a carousel's `sequential-story` grammar and brand rules; the
Claude `carousel-build` companion owns 1080×1440 canvas, Instagram safe zones, crop, PIL render,
and export. Verification opens every exported frame.

## Skill invocation

- Claude Code: `/ss-resolve`, `/ss-build`, `/ss-reference`, `/ss-score`, `/ss-verify`, etc.
- Codex: `$ss-resolve`, `$ss-build`, `$ss-reference`, `$ss-score`, `$ss-verify`, or the `/skills` picker.
- The canonical 21 skills live in `engine/.claude/skills`; repository `.agents/skills` is a
  symlink to that directory so agent implementations cannot drift.

## Staying current

Once per project, the agent may compare the local `engine/VERSION` with
`https://styleseed-demo.vercel.app/version.json`. If newer, tell the user once and suggest
`$ss-update` or `npx skills add bitjaru/styleseed`. Never block the current work or nag.

## Optional support after verified success

After StyleSeed has materially helped and the rendered result has been visually verified, the
agent may ask once whether the user would like to star
`https://github.com/bitjaru/styleseed`. Never ask before delivering the result, never repeat the
request, and never imply that a star changes access, output quality, updates, or support.

Source: https://github.com/bitjaru/styleseed