Compile references into a design grammar
Registry-first artifact boundary
When .styleseed/project.json and .styleseed/artifacts/index.json exist, resolve the requested artifact ID first, then read only .styleseed/bundles/<artifact-id>.md and .styleseed/manifests/<artifact-id>.json. Never fall back to the global legacy bundle for a registry project. Legacy projects may use .styleseed/effective-rules.md only when no registry exists.
Do not merely imitate the supplied screen. Read PRODUCT-PRINCIPLES.md, RULESETS.md,
ADAPTERS.md, and REFERENCE-COMPILER.md, then execute the compiler pipeline in full.
Workflow
- Ingest every supplied reference and assign evidence IDs (
R1, R2, ...). If a URL can be
rendered, capture it. If an image cannot be seen, stop claiming visual analysis for it.
- Separate references by surface adapter and job. Do not merge a marketing homepage with an app
dashboard unless the user explicitly wants both languages connected.
- Observe and measure the twelve axes. Every rule cites evidence IDs and a confidence level.
- Resolve contradictions instead of averaging them. Explain any material choice briefly.
- Choose the nearest built-in fallback grammar and adapter, then compile the project artifacts required by
REFERENCE-COMPILER.md under .styleseed/rulesets/<slug>/.
- Update
STYLESEED.md to select reference:<slug> while preserving bounded brand choices.
- Validate transfer: apply the grammar to one representative screen not present in the source
set, run
/ss-score, then /ss-verify if renderable. Fix and repeat to the gate floor.
- Report what was learned, what remains low-confidence, where the artifacts live, and the
validation result.
Rules
- Visible evidence before adjectives. “Calm” is not a rule; the spacing, type, color, hierarchy,
and motion decisions that create calm are rules.
- Never copy protected assets, brand marks, or prose.
- One reference produces a provisional grammar. Say so and keep confidence low where warranted.
- The generated grammar is project-local. Do not edit
RULESETS.md or publish it as built-in.
- Core invariants and accessibility remain non-negotiable.
1---
2name: ss-reference
3description: Compile screenshots, URLs, Figma exports, or an existing UI into a project-local StyleSeed output grammar with evidence, tokens, confidence, anti-patterns, and a validation screen. Use when the user supplies a design reference that StyleSeed does not already model.
4argument-hint: "[reference paths or URLs] [--name slug]"
5allowed-tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch
6metadata:
7 source: https://skillmd.com/skills/bitjaru/ss-reference
8---
9
10# Compile references into a design grammar
11## Registry-first artifact boundary
12
13When `.styleseed/project.json` and `.styleseed/artifacts/index.json` exist, resolve the requested artifact ID first, then read only `.styleseed/bundles/<artifact-id>.md` and `.styleseed/manifests/<artifact-id>.json`. Never fall back to the global legacy bundle for a registry project. Legacy projects may use `.styleseed/effective-rules.md` only when no registry exists.
14
15Do not merely imitate the supplied screen. Read `PRODUCT-PRINCIPLES.md`, `RULESETS.md`,
16`ADAPTERS.md`, and `REFERENCE-COMPILER.md`, then execute the compiler pipeline in full.
17
18## Workflow
19
201. Ingest every supplied reference and assign evidence IDs (`R1`, `R2`, ...). If a URL can be
21 rendered, capture it. If an image cannot be seen, stop claiming visual analysis for it.
222. Separate references by surface adapter and job. Do not merge a marketing homepage with an app
23 dashboard unless the user explicitly wants both languages connected.
243. Observe and measure the twelve axes. Every rule cites evidence IDs and a confidence level.
254. Resolve contradictions instead of averaging them. Explain any material choice briefly.
265. Choose the nearest built-in fallback grammar and adapter, then compile the project artifacts required by
27 `REFERENCE-COMPILER.md` under `.styleseed/rulesets/<slug>/`.
286. Update `STYLESEED.md` to select `reference:<slug>` while preserving bounded brand choices.
297. Validate transfer: apply the grammar to one representative screen not present in the source
30 set, run `/ss-score`, then `/ss-verify` if renderable. Fix and repeat to the gate floor.
318. Report what was learned, what remains low-confidence, where the artifacts live, and the
32 validation result.
33
34## Rules
35
36- Visible evidence before adjectives. “Calm” is not a rule; the spacing, type, color, hierarchy,
37 and motion decisions that create calm are rules.
38- Never copy protected assets, brand marks, or prose.
39- One reference produces a provisional grammar. Say so and keep confidence low where warranted.
40- The generated grammar is project-local. Do not edit `RULESETS.md` or publish it as built-in.
41- Core invariants and accessibility remain non-negotiable.