/ss-lint

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:

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

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.

Checks

1. Hardcoded Colors

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

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

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

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

3. Old Width/Height Syntax

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

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

4. Physical Properties (LTR-only)

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

**Violation:** `ml-2`, `mr-4` **Fix:** `ms-2`, `me-4`

5. Uncontracted Hard Black

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

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)

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()

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.