ds-audit

name	ds-audit
description	Audit a React + Tailwind codebase against the SaaS Panel design system and report violations ranked by impact, with the exact fix for each. Use when the user asks to review, audit, check or fix UI consistency, before merging a screen, when a screen "looks off" compared to the rest of the product, or to find drift such as fixed page sizes, drawers used for record details, Tabs used as page sub-navigation, hardcoded hex colors, missing loading/error/empty states, or unpatched shadcn primitives.
license	MIT
compatibility	Any React + Tailwind CSS codebase. Assumes the SaaS Panel design system is installed or being adopted; read-only by default.
metadata	{"version":"1.0.0","part-of":"saas-panel-design-system"}

Audit against the SaaS Panel design system

Read-only by default: find and report, fix only when the user asks. Rank findings by what a user actually feels, not by how many times a rule appears.

Reference material: ../saas-panel-design-system/references/. The full antipattern catalog with the historical bug behind each rule is in 16-checklists-e-antipadroes.md.

Scope

Ask (or infer from context) what to audit:

• the current diff / branch → git diff main...HEAD --name-only | grep -E '\.tsx?$'
• one screen or directory
• the whole src/ (say up front that this can be long, and report by severity)

Detection sweep

Run these first — they find most of the drift in seconds. Each hit is a candidate, not yet a finding: open the file and confirm before reporting.

# ── Blockers ───────────────────────────────────────────────────────────────
grep -rn "PAGE_SIZE\s*=\s*[0-9]" src --include=*.tsx        # fixed page size
grep -rln "components/ui/sheet" src --include=*.tsx          # drawer — check if it is a record detail
grep -rln "components/ui/tabs" src --include=*.tsx           # Tabs — check if it is page sub-navigation
grep -rnE "#[0-9a-fA-F]{6}\b" src --include=*.tsx            # loose hex
grep -rn "window.confirm" src --include=*.tsx                # unconfirmed destructive action

# ── High ───────────────────────────────────────────────────────────────────
grep -rn "h-\[[0-9]\+vh\]" src --include=*.tsx               # fixed modal height
grep -rn "text-primary\b" src --include=*.tsx | grep -v "dark:" | head -20   # solid accent w/o dark variant
grep -rn "toast(" src/components src/pages --include=*.tsx   # toast in component instead of hook
grep -rn "\.slice(.*currentPage" src --include=*.tsx         # manual pagination

# ── Medium ─────────────────────────────────────────────────────────────────
grep -rn "onChange=.*setSearch" src --include=*.tsx          # search without debounce?
grep -rLn "tabular-nums" src --include=*.tsx                 # numeric columns w/o tabular figures
grep -rn "ArrowLeft\|ChevronLeft" src/pages --include=*.tsx  # "Back" button under the shell

Checklist by area

Confirm each candidate against the rule. Only report what you verified.

Structure (blocker)

• Record detail uses <DetailModal> — not <Sheet>/drawer. (Sheet is legitimate in a builder's config panel and in ui/sidebar.)
• Page sub-navigation uses <PageSubnav> or promoted sidebar items — not <Tabs>. (Tabs is legitimate for sub-tabs inside a builder.)
• No "Edit data" tab in a detail modal; fields edit in place via <InlineField>.
• List screens follow the 4 blocks: PageHeader → StatsGrid → filter Card → ListCard. Action buttons sit in PageHeader, not loose above the table.
• No "Project"/tenant column when a global context selector already filters.
• No "Back" button on pages rendered under the shell (the breadcrumb covers it).

Data behaviour (blocker/high)

• Pagination is adaptive (usePagination(items, { auto: true })) — no fixed size.
• Pipeline order is filter → sort → paginate; sorting spans the whole list.
• resetPage() runs when filters and sort change.
• Search debounced at 300ms; the raw value feeds the input, the debounced one the filter.
• Empty state lives inside <TableBody>, never as an early return that replaces the screen.
• Empty message distinguishes "no search results" from "filter empty" from "no data yet".

States (high)

• loading, error and empty all covered.
• Error shows the cause and a retry.
• Destructive actions use AlertDialog naming the record and the consequence.
• Blocked actions are disabled with a tooltip explaining why — not hidden.
• Async buttons change label or icon and are disabled while running.

Style (high/medium)

• No hex literals; colors come from tokens or the closed accent vocabulary (emerald, sky, violet, amber, rose, primary).
• Solid accents carry a dark-mode variant (dark:*-primary-glow).
• Modals grow to max-h-[88vh]; no fixed h-[..vh].
• min-w-0 on flex text containers, shrink-0 on adjacent icons.
• tabular-nums on comparable numbers; Intl for formatting; — for absent values (never R$ 0,00 or 0% for missing data).
• Icons w-4 h-4 in buttons, w-5 h-5 standalone.
• components/ui/** not edited ad hoc — customization lives in wrappers.

Primitives (medium)

Compare against ../saas-panel-design-system/assets/primitives/:

• button at h-9 with ring-primary/20 focus
• card rounded-xl border-border/60 p-5
• input/textarea/select h-9 with the thin green focus ring
• table head uppercase/xs/muted, rows hover:bg-muted/40
• dialog p-5 gap-3

Accessibility (high)

• Interactive elements are <button>/<a>, not <div onClick>.
• Icon-only controls have aria-label or title.
• aria-current="page" on the active navigation item.
• Focus ring never removed without a replacement.
• Color is never the only channel carrying meaning.
• Modals with JSX titles pass srTitle / srDescription.

Report format

Group by severity, most severe first. One line per finding, with the exact location and the exact fix. Do not pad the report with rules that passed.

## Design system audit — <scope>

### Blockers (2)
1. `src/pages/Contacts.tsx:34` — fixed `PAGE_SIZE = 10`.
   → `usePagination(sorted, { auto: true })` + `<ListCard ref availableHeight>`.
   Why it matters: half-empty list on any large screen.
2. `src/components/ContactDrawer.tsx` — record details rendered in a `<Sheet>`.
   → Rebuild with `<DetailModal>` + section sidebar (references/10-padrao-modais.md).

### High (3)
…

### Medium (5)
…

### Clean
Tokens, primitives and states follow the system in the audited scope.

Close with the single highest-leverage fix — the one that removes the most inconsistency for the least work — and offer to apply the fixes.

When fixing

Only after the user asks. Then:

1. Fix blockers first; do not bundle unrelated refactors.
2. Copy from ../saas-panel-design-system/assets/ instead of hand-writing.
3. Re-run tsc --noEmit, lint and build.
4. Report what changed, what you deliberately left alone, and why.