tt-polish

Polish is a two-phase pass, not a builder. It assumes TUX token compliance is already mostly in place — if it isn't, run /tt-impeccable extract first.

Phase 1 — Visual Elevation: adds warmth, depth, and richness that survive token compliance but are not prescribed by the core spec. Phase 2 — Compliance Sweep: catches token drift, missing states, anti-patterns, and copy issues.

---

Context Check

1. Read .tt-impeccable.md in project root if it exists — fidelity tier and design context are there.
2. If absent, infer tier from codebase: mobile-first 390px = Strict TUX-native; dark #000000 desktop = TT Style.
3. Only ask if the tier is genuinely ambiguous.

Note the fidelity tier: Phase 1 rules apply primarily to Strict TUX-native light-theme surfaces. Phase 2 applies to both tiers.

---

Phase 1: Visual Elevation

Load reference/polish-rules.md and apply all 13 rules systematically.

Rule summary (refer to the rules file for full CSS and constraints):

#	If… (condition)	→ Then (action)
1	Page has a prominent heading (font-size > 17px)	Left-align it, add a subtitle line below, place a radial-gradient glow at top — height = heading's top offset + 20px so gradient is fully transparent by the time the heading begins; color from Ambient Glow presets (rules file); skip on utility/settings screens
2	Largest font-size on page < 20px	Set one heading to 24–32px (scale to content density); compress smallest body text to 12px
3	Page horizontal margin < 20px, or element gaps feel tight	Set page padding to 20px; inter-group vertical gaps to 24–32px
4	Card or icon list cell present	Replace every icon with a contextual emoji; set background to ~5% tint of dominant hue using oklch() (keeps color vivid)
5	Card or cell border-radius < 12px	Upgrade: L1 nested → 14px, L2 overlay/sheet → 26px
6	2–5 emoji list cells present	Shorten label text, foreground the emoji, reflow as a 2-column card grid
7	Same-type cards in a grid	Enforce a consistent internal layout system across all cards: same emoji size, same title position, same description line count, same padding — no card should look structurally different from its siblings
8	Divider lines present	Replace with fading-edge gradient; attach to scroll wrapper (not chrome elements)
9	≥3 distinct non-neutral colors on screen	Switch CTA button to black (#000000) with white label
10	Icon sizes other than 24px or 16px present	Snap large icons → 24px, small icons → 16px; enforce one size per component
11	Solid non-neutral fill (red, blue, etc.) > 30px wide/tall with icon inside	Remove the fill container; promote the associated title to 24px/700 dominant typography
12	Entrance animations absent	Add: cards fadeUp staggered 40ms, sheets fadeScale 220ms, chips fadeIn staggered 30ms; disable translate/scale under prefers-reduced-motion
13	Group/section label is visually stronger than item titles inside it	Demote label to 13px/600/text-2; item titles stay at 15–17px/700/text-1-display — the label is wayfinding, not a headline

Phase 1 rules apply to Strict TUX-native light-theme surfaces. For TT Style surfaces, Rules 2, 3, 5, 10, 11 still apply; Rules 1, 7, 12 are adapted (see rules file for TT Style notes).

---

Phase 2: Compliance Sweep

2a — Token Drift Scan

Read source files and search for:

• border:, border-top:, border-bottom:, border-left:, border-right: — for each hit: (a) could a background color change replace it? (b) Is it compensating for wrong surface contrast? Flag P1/P2 as appropriate.
• :hover rules containing border-color or adding a border — convert to background/opacity changes (P2)
• backdrop-filter — confirm glassmorphism is explicitly confirmed in context; if not, remove (P1)
• letter-spacing non-zero on text below 72px — remove (P2)
• rgba(254,44,85,*) at any alpha on non-CTA/non-interactive elements — BAN 7 violation (P1)
• Accent color (brand red, teal) on elements without interactive semantics (no onClick/href/role) — replace with neutral (P1)
• Hard-coded hex or rgba values not going through var(--tux-*) — flag all (P2)
• Spacing values not in the TUX 4px grid (4/8/12/16/20/24/32) — flag off-grid values (P2)
• border-radius values not in the TUX tables — flag (P2)
• box-shadow values that don't match the 6 TUX levels — flag (P2)
• Font other than TikTok Sans / system-ui — flag (P1)
• overflow: hidden on text containers with line-height below 1.0em — add descender padding fix (P2)

2b — Interaction States

Confirm every interactive element has all applicable states:

• Default — resting appearance
• Active / pressed — opacity drop or background shift on touch
• Focus-visible — keyboard/accessibility ring; never outline: none without replacement
• Disabled — visually de-emphasized; pointer-events: none
• Loading — if async: spinner, skeleton, or progress; element must not look tappable while loading
• Error — if element can fail: validation state visible
• Success — if action has meaningful completion: confirmation or state change

Touch target minimum: 44×44px on every tappable element.

2c — Entrance Animations (from Phase 1 Rule 12)

• All elements have entrance animations — no element snaps into existence at full opacity
• Cards/items use staggered fadeUp; floats use fadeScale; chips use staggered fadeIn
• prefers-reduced-motion: translate/scale animations disabled; opacity-only or none

---

Phase 1 Checklist (before presenting)

Gradients & Glow

• Page has heading > 17px → gradient applied; fades fully transparent before 220px
• Maximum one glow source per page

Typography

• Whole-page: largest text ≥ 24px, smallest ≤ 12px
• Within each module: at least one 700-weight dominant and one 400-weight/12px recessive element
• Adjacent tiers differ by ≥ 2 steps on the TUX scale

Spacing

• Page horizontal padding is 20px
• Inter-group vertical gaps are 24–32px
• Card internal padding is 20–24px

Cards & Emoji

• All SVG/system icons in cards and list cells replaced with contextual emoji
• Card/cell backgrounds use oklch() tint at ~5% — not flat rgba()
• Card label/heading color carries the card's hue
• 2–5 emoji list cells reflowed as 2-column card grid
• White-on-white: card gets tinted background

Fills & Color Restraint

• No solid non-neutral fill > 30px containing an icon — removed and replaced with dominant title
• CTA: ≥3 distinct non-neutral colors on screen → CTA is black

Surface & Structure

• Radius: L1 nested ≥ 14px; L2 overlay = 26px
• Same-type card grid: all cards share identical internal structure (emoji size, title position, description lines, padding)

Fading Edges

• Dividers replaced with fading-edge gradient attached to scroll wrapper
• Fade color matches scroll surface background
• Fade height ≥ 32px

Icons

• Icon sizes snapped to 24px (large) or 16px (small); one size per component

Typography Hierarchy

• Group/section labels are ≤13px/600/text-2 — weaker than item titles inside them

Animations

• Cards: fadeUp staggered 40ms per item
• Sheets/modals: fadeScale 220ms
• Chips: fadeIn staggered 30ms
• prefers-reduced-motion: translate/scale disabled

---

Final Verification

1. Use it yourself — interact with every state and flow
2. Run /tt-audit — confirm health score improved
3. Re-run /tt-critique — verify anti-pattern verdict is clean

Polish is complete when the interface is indistinguishable from a screen inside the TikTok app — not because it has the right tokens, but because it has the right feel.