/ss-score

name: ss-score
description: Score a visual artifact's implementation quality 0-100 against its composed StyleSeed rule set — category breakdown, evidence, and prioritized fixes.
argument-hint: "[file, directory, or artifact manifest]"
allowed-tools: Read, Grep, Glob, Bash

Design Score

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.

Deterministic check boundary

For the executable contract and stable diagnostics, run the canonical checker:

node <installed-ss-score>/scripts/styleseed-check.mjs scan \
  --project-root . --artifact <artifact-id> --format json
node <installed-ss-score>/scripts/styleseed-check.mjs scan \
  --project-root . --artifact <artifact-id> --format sarif --out .styleseed/evidence/<artifact>/<run>/deterministic.sarif

The checker revalidates the artifact manifest, bundle/output hashes, declared source roots, and project containment before scanning. Contract/path/hash/coverage failures are hard errors. Source detectors are warning-only until their fixture precision is measured and a maintainer promotes them. Stable detector IDs are `SS001` hardcoded colors, `SS002` arbitrary pixel values, `SS003` `transition-all`, `SS004` motion without reduced-motion handling, `SS005` focus suppression, and `SS006` high-confidence unlabeled icon controls. A deterministic JSON report contains only `detectorRevision`, `inventoryHash`, and sorted `findings`, so it can be attached to the evidence gate without caller-supplied pass claims.

Attach the generated JSON through the same typed gate path as other reports:

node <installed-ss-score>/scripts/evidence-gate.mjs attach \
  --project-root . --artifact <artifact-id> --run <run-id> \
  --gate deterministic \
  --report .styleseed/evidence/<artifact-id>/<run-id>/deterministic.json

`/ss-review` tells you *what's wrong*. `/ss-score` tells you *how good it is overall* and *what to fix first* — a single number plus a category breakdown, so you can track UI quality like you track test coverage.

When NOT to use

• For a quick pass/fail before committing → use `/ss-lint`
• For a full prose audit with fixes → use `/ss-review`
• For logic/config with no visual artifact — scoring is meaningless

Step 0 — Resolve the effective rule set

Before scoring, apply the registry-first artifact boundary above. Registry projects read `.styleseed/bundles/<artifact-id>.md` and `.styleseed/manifests/<artifact-id>.json`; check with `ss-resolve --artifact <artifact-id> --check`. A partial or invalid registry is an error, never a reason to use the legacy bundle or source handbook.

Legacy projects without a registry read `.styleseed/effective-rules.md` and `.styleseed/manifest.json`, using `ss-resolve --from-lock STYLESEED.md --check`. If the selected bundle is missing or stale, invoke `/ss-resolve` or `$ss-resolve` from the corresponding project-owned configuration first. With no registry or lock, resolve the intended scope with the user before making a project-specific compliance claim.

Score in authority order: core invariants first, then the exact output grammar, domain/page, brand recipe, optional aesthetic profile, and bounded lock values. The lock cannot waive an invariant. Unknown values are a resolver error; do not invent an exception.

The output must name the effective rule set, for example:

Rule set: operations-console × SaaS × dashboard × enterprise-workbench × swiss

What to score

Score the file (or each file in a directory) on **eight weighted categories** that map to the design language. Total = 100.

| Category | Weight | Reads from | |---|---|---| | **Color discipline** | 16 | DESIGN-LANGUAGE §1, §18, §72 + VISUAL-CRAFT §C4 | | **Hierarchy & typography** | 16 | §2, §3, §4, §16 + Font Size table + VISUAL-CRAFT §C2 | | **Layout & rhythm** | 12 | §13, §14, §15, §61 + VISUAL-CRAFT §C1 | | **Cards & elevation** | 10 | §7, §8, §12, §1 + VISUAL-CRAFT §C3 | | **States & a11y** | 18 | §11, §70, §71, §72 + VISUAL-CRAFT §C3 | | **Motion & interaction** | 6 | §24, §59 + `engine/motion` | | **Coherence** | 12 | VISUAL-CRAFT §C0 (one choice per axis) | | **Distinctiveness** | 10 | Golden Rules 14–16 + VISUAL-CRAFT §CC-9b (not generic/default/template) |

How to score each category

For each category, start at full marks and **subtract** for violations you find by reading the code. Be specific and evidence-based — cite the line.

**Color discipline (16)** — deduct for: accidental `#000`/`text-black` outside a profile or grammar contract that explicitly uses hard black structurally (−4 each, cap −8); competing decorative emphasis hues (−5); **emoji used as UI icons** (−5); **a normal/OK/"보통" state shown in a status color** instead of neutral grey (−4); **status color on most/every row** (no severity hierarchy) (−4); **decorative hues** (gold stars, rainbow category dots) instead of accent/grey (−3); hardcoded hex where a semantic token exists (−2 each, cap −6); status conveyed by color alone (−4); **the unlocked default indigo (`#5E6AD2`/`#4F46E5`) used as the accent** instead of a chosen domain-fit color (−4).

**Distinctiveness (10)** — a coherent screen can still read "AI-generated." Deduct for: the **icon-chip cliché** — a generic Lucide line-icon in an identical pale-tinted rounded-square, repeated for every feature/step (−4, §CC-9b); the **StyleSeed demo layout copied verbatim** (hero+chat / 3-step / feature-grid / pricing) with no product-specific identity (−4); **no focal point** — an all-even grid of same-weight, centered, evenly-spaced cards (−3); the hero shows a stock/placeholder visual instead of *this* product (−3); the **escape h