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

Before this workflow, follow the once-per-session [update preflight](../ss-update/references/update-preflight.md).


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

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 findings; an authorized implementation step owns fixes

Target: **$ARGUMENTS**

## What This Does

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.