frontend

Files (7)

• SKILL.md
• bootstrap-react.md · references/
• existing-system-react.md · references/
• non-react.md · references/
• retrofit-react.md · references/
• visual-loop.md · references/
• detect.py · scripts/

SKILL.md (first lines)

# Frontend polish

Turn whatever frontend state a repo is in — nothing, something inconsistent, or an already
mature design system — into a cohesive, professional result, while making as few design
decisions on the user's behalf as possible without asking for their taste directly. Follow
these steps in order.

## 1. Precondition: aesthetic guardrails

This skill orchestrates *what* gets changed; it deliberately does not carry its own aesthetic
guidance, because the official `frontend-design` skill already covers that (avoiding generic
AI-slop palettes and typography, a plan-review-build-critique process). Check whether that
skill is available in this session.

If it is not available: tell the user it's required for good results and offer to install it
(`/plugin install frontend-design@claude-plugins-official`). Only continue without it if the
user explicitly says to proceed anyway — and if so, note in the final report that aesthetic
guardrails were skipped for this run.

## 2. Precondition: git safety

Run `git status --porcelain` in the target repo. If it's not a git repository, or the working
tree isn't clean, stop and ask the user whether to proceed anyway, commit/stash first, or create
a throwaway branch. Do not write any files until the tree is clean or the user has explicitly
accepted the risk.

## 3. Detect

Run `python "<skill-dir>/scripts/detect.py" <repo-root>` (substitute the actual path to this
skill's directory and the repo being worked on). This is a deterministic scan — trust its
`evidence` field over any impression from skimming the repo yourself, and show that evidence to
the user later rather than restating a bare verdict.

It returns:
- `framework`: `next`, `react`, or `other`
- `maturity`: `bootstrap` (no real UI system yet) or `existing` (some system is present)
- `signal`: `found` or `none` — `none` means detection was inconclusive, not that the repo is
  empty
- `evidence`: the concrete facts behind the classification

## 4. Classify and pick a path

- `framework` is `next` or `react`, `maturity` is `bootstrap` → `references/bootstrap-react.md`
- `framework` is `next` or `react`, `maturity` is `existing` → read the `evidence`, then form a
  recommendation between two paths (do not treat this as fact — it's your read of the evidence,
  and the user can override it at the confirm gate):
  - `references/retrofit-react.md` if the evidence points to inconsistent or ad hoc styling
    (many small CSS files, mixed/no component library, no coherent token system)
  - `references/existing-system-react.md` if the evidence points to one coherent system already
    in place (a real component library, a design-token setup, few one-off styles)
- `framework` is `other`, or `signal` is `none` → `references/non-react.md`, regardless of
  `maturity`. If `signal` is `none`, tell the user at the confirm gate that detection was
  inconclusive so they can correct the path before anything is touched.

## 5. Confirm gate

Before writing anything, present:
- the detected classification and its evidence
- the chosen path (and the recommended alternative, for react+existing repos, so the user can
  switch)
- the theme or token direction you'd apply, already picked — don't ask the user to choose a
  theme, just show what you picked and why
- a draft `DESIGN.md` for the target repo
- the file allowlist this run will stay inside — the specific files/directories relevant to the
  chosen path (see each reference file for its scope), plus `DESIGN.md` and, if a component
  library is being installed, `package.json`

Treat this as a negotiation, not a yes/no gate. If the user pushes back on any part — wrong
path, disagrees with the theme, wants a file excluded — revise that part and present again
rather than starting over or proceeding regardless. Only move to execution once the user gives
an explicit go-ahead.

## 6. Execute

Follow the chosen reference file. Stay inside the allowlist confirmed in step 5. Write
`DESIGN.md` into the target repo — this is the one artifact from this whole skill that's
project-specific, since it describes that project's actual design system, not this skill's
process.

## 7. Enforce the allowlist

Before reporting anything as done, run `git diff --name-only` and `git status --porcelain` in
the target repo and check every changed or new path against the allowlist confirmed at the gate.
If anything falls outside it, stop and tell the user exactly what was touched beyond scope — let
them decide whether to keep it, rather than shipping it silently.

## 8. Verify

Follow `references/visual-loop.md` for a bounded screenshot-critique-fix pass against the
running app.

## 9. Report

Summarize: which path was taken, which files changed (cross-checked against the allowlist in
step 7), what the visual loop found and fixed, screenshots if available, and anything left
unresolved within its iteration budget.

From jpol34/polyak-dev-kit, MIT.

More from jpol34/polyak-dev-kit