ss-lint · diff

git:20260819.139d7f3 to git:20260916.7029afe

10 added, 4 removed. Audit A to A.

---

name: ss-lint

description: Quick automated lint — detects common design system violations in seconds

argument-hint: "[file-path or directory]"

allowed-tools: Read, Grep, Glob, Bash

---

# Design Lint (Quick Check)

## 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.

## Canonical executable check

For a reproducible, artifact-bound scan with machine-readable output, use:

```bash

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 . --all --format sarif

```

The checker treats only contract, containment, manifest/hash, malformed-report, and required

coverage failures as hard errors. Detector findings (`SS001`–`SS006`) remain warnings and include a

stable file, line, evidence snippet, severity, and fix. Use `styleseed-check ... verify` to recompute

the bound evidence run; do not turn a string or stale report into a pass.

- Read `.styleseed/effective-rules.md` and `.styleseed/manifest.json`; invoke `/ss-resolve` or

- `$ss-resolve` first when they are missing or stale. Lint detects deterministic drift; it must

+ If either registry file exists, require a complete, valid registry and check only the selected

+ artifact's bundle and manifest. Only when neither registry file exists, read

+ `.styleseed/effective-rules.md` and `.styleseed/manifest.json`. Report missing or stale evidence

+ without regenerating bundles during a lint-only request. Lint detects deterministic drift; it must

not flag an exact grammar/recipe/profile/adapter contract as a violation or let an arbitrary lock

value create an exception.

## When NOT to use

- For deeper review of design judgment (composition, hierarchy, rhythm) → use `/ss-review`

- For accessibility specifically → use `/ss-a11y`

- For Nielsen UX heuristics → use `/ss-audit`

- - For applying refactors — this only flags violations; use `/ss-review` to fix

+ - For applying refactors — this only flags findings; an authorized implementation step owns fixes

Target: **$ARGUMENTS**

## What This Does

- Fast, grep-based scan for common design violations. Runs in seconds (unlike /ss-review which is a deep manual audit). Run this after every file change.

+ Use the canonical checker above for executable diagnostics. The searches below are manual

+ review hints for applicable project conventions, not additional hard-error detectors. Run on

+ affected UI files when requested or required by the build workflow; do not lint unrelated edits.

+ Do not edit code in lint-only mode. Once required checks pass, repeat only after relevant changes

+ or new evidence of a problem. Use `--all` only when all artifacts are explicitly in scope.

## Checks

### 1. Hardcoded Colors

Search for hex colors in className strings that should be semantic tokens:

```bash

grep -n '#[0-9a-fA-F]\{3,8\}' [file] | grep -v 'theme.css\|tokens\|\.json'

```

**Violation:** `text-[#3C3C3C]`, `bg-[#3182F6]`

**Fix:** `text-text-primary`, `bg-brand`

### 2. Raw Pixel Values in Tailwind

```bash

grep -n 'p-\[.*px\]\|m-\[.*px\]\|gap-\[.*px\]' [file]

```

**Violation:** `p-[24px]`, `gap-[12px]`

**Fix:** `p-6`, `gap-3`

### 3. Old Width/Height Syntax

```bash

grep -n 'w-[0-9] h-[0-9]\|w-\[.*\] h-\[' [file]

```

**Violation:** `w-4 h-4`

**Fix:** `size-4`

### 4. Physical Properties (LTR-only)

```bash

grep -n ' ml-\| mr-\| pl-\| pr-' [file]

```

**Violation:** `ml-2`, `mr-4`

**Fix:** `ms-2`, `me-4`

### 5. Uncontracted Hard Black

```bash

grep -n 'text-black\|bg-black\|#000000\|#000"' [file]

```

**Violation:** Pure black without an exact structural role in the selected grammar/profile

**Fix:** Use the semantic ink token, or cite the maintained contract that requires hard black

### 6. Missing data-slot

```bash

grep -n 'function [A-Z]' [file] # find components

grep -n 'data-slot' [file] # check if present

```

**Violation:** Component without `data-slot`

**Fix:** Add `data-slot="component-name"`

### 7. Font Size CSS Variables (CRITICAL — Tailwind v4 conflict)

```bash

grep -n 'text-\[var(--' [file]

grep -n '\-\-text-.*px\|--fs-.*px' [file]

```

**Violation:** `text-[var(--text-sm)]` or `--text-sm: 13px` in theme.css

**Fix:** Use explicit `text-[13px]`. CSS variable font sizes conflict with Tailwind v4's `--text-*` namespace — Tailwind reads them as color, not font-size.

### 8. className Without cn()

```bash

grep -n 'className={`' [file]

```

**Violation:** Template literal className

**Fix:** Use `cn()` for all className composition

### 9. Universal Soft-card Drift

Search for repeated `rounded-2xl`, `shadow-[var(--shadow-card)]`, and `mx-6` in pattern files.

Flag the combination when the selected recipe is not `calm-consumer`.

**Fix:** use `ss-pattern-surface`, `ss-page-gutter`, and the other recipe-aware helper classes.

## Output Format

```

🔴 FAIL [file:line] Hardcoded hex: text-[#3C3C3C] → use text-text-primary

🔴 FAIL [file:line] Raw px: p-[24px] → use p-6

🟡 WARN [file:line] Physical prop: ml-2 → use ms-2

🟡 WARN [file:line] Missing data-slot on MyComponent

🟢 PASS No violations found

Total: X errors, Y warnings

```

If errors > 0, list specific fixes for each violation.