Ss Score

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.

Within an authorized evidence-writing/build task, attach the generated JSON through the same typed gate path as other reports. Plain scoring reports findings without attaching evidence:

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 and recommendations → use /ss-review; applying fixes is a separate, authorized implementation step
• 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, plain scoring reports missing evidence without regeneration. Within an authorized build/fix task, 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.

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 hatch as a new uniform (§CC-9c) — ghost 01/02/03 index numbers on every section, or identical uppercase-overline + big-number cards repeated with no variation (−2); distinctive-but-dated (§CC-9d) — full beige/paper page base, serif body text on a product surface, dark-heavy blocks that read "brochure" not "2026 product" (−3). Cap −10.

Hierarchy & typography (16) — deduct for: value/unit hierarchy contradicting the selected grammar (−4; compact/tabular and prose-like relationships are valid when specified); type roles that drift from the compiled contract or CSS that renders the wrong size (−5); everything the same weight, no clear primary (−5); cramped or wrong line-height on body (−3); body < 16px on a desktop/web B2B surface (tight mobile scale on a wide screen) (−4 — but dense-data chrome is exempt: chart ticks, mono SHAs/timestamps, table metadata at 12–13px are correct; and dashboard app-chrome h1 at 22–24px is correct, not a violation of the marketing 40–56px headline scale).

Layout & rhythm (12) — deduct for: grouping that contradicts the selected grammar or recipe (−6): operations-console needs explicit functional groups, while editorial-reading should not be forced into cards; enterprise-workbench needs aligned panels/rows while public-service needs flat step flow; arbitrary off-scale spacing (−3); same section type repeated without purpose (−4); no discernible proximity rhythm (−3).

Cards & elevation (10) — deduct for mixed or task-inappropriate surface language. Hairlines, flat grouping, tonal ramps, or restrained shadows are valid only when the selected grammar/profile uses them coherently. Deduct mixed border/shadow languages (−4), visibly heavy or directionally inconsistent shadows (−4), or missing group/surface separation where the grammar requires it (−5).

States & a11y (18) — deduct for: missing empty/loading/error state on a data