Plan a UI hygiene day-of-week cadence that cleans up CSS debt, removes unused tokens,…
- User
Plan a UI hygiene day-of-week cadence that cleans up CSS debt, removes unused tokens, and refreshes Storybook snapshots.
Assistant
The user wants a plan for a "UI hygiene" cadence, specifically broken down by day of the week. The goal is to clean up CSS debt, remove unused tokens, and refresh Storybook snapshots. I need to structure this as a recurring weekly schedule (a "cadence").
Analysis of the Request:
- Scope: CSS debt, Design Tokens, Storybook snapshots.
- Cadence: Day-of-week (suggesting a weekly routine).
- Goal: "UI Hygiene" (maintenance, cleanup, consistency).
Challenges/Constraints:
- A weekly cadence for deep cleaning (like CSS refactoring) might be too aggressive for a large codebase, but perfect for a focused maintenance strategy.
- "Day-of-week" implies specific tasks for specific days, leading up to a release or a check-in point.
- The tasks need to be actionable and varied to prevent burnout.
Proposed Strategy: I will create a weekly schedule (e.g., Monday to Friday) where each day focuses on a specific aspect of the cleanup. This spreads the workload and allows for different types of cognitive load (automation vs. manual review vs. testing).
- Monday: Detection & Audit (The "What") - Start the week by finding the problems. Running scripts to find unused CSS/tokens.
- Tuesday: Token & Variable Cleanup (The "Source") - addressing the design tokens before the CSS.
- Wednesday: CSS Refactoring (The "Heavy Lifting") - Removing the unused classes/Debt.
- Thursday: Component & Storybook Maintenance (The "Verification") - Updating stories and running snapshots.
- Friday: Review & Documentation (The "Wrap up") - PRs, documentation updates, planning next week.
Drafting the Content - Step-by-Step:
- Monday: Detection.
- Tools: Stylelint, CSS stats, unused CSS finders (PurgeCSS reports, etc.).
- Action: Generate a report of unused selectors or low-utility tokens.
- Tuesday: Design Tokens.
- Focus:
variables.css, JSON tokens. - Action: Deprecate duplicates, remove aliases that go nowhere. Sync with Figma if possible.
- Focus:
- Wednesday: CSS/Styles Cleanup.
- Focus: Actual deletion.
- Action: Delete the unused classes identified on Monday. Consolidate utility classes.
- Thursday: Storybook & Snapshots.
- Focus: Visual regression and documentation.
- Action: Update story args, fix broken knobs/controls, update snapshots (chromatic or local).
- Friday: Merge & Retro.
- Focus: Integration.
- Action: Merge the PRs. Update the "UI Hygiene" log.
Refining the Approach: A strict "Weekly" cadence might be too frequent for heavy refactoring, but good for maintenance. I should frame this as a "Sustainable Weekly Sprint."
Let's add specific tooling recommendations for each step to make it actionable.
- CSS: PurgeCSS, UnCSS, Chrome DevTools Coverage.
- Tokens: Style Dictionary checks, Theo.
- Storybook: Storyshots, Chromatic.
Structure of the Response:
- Philosophy: Why this cadence works (prevention vs. cure).
- The Schedule (Mon-Fri): Detailed breakdown.
- Tooling Checklist: How to automate the manual labor.
- Governance: How to keep the team aligned.
Self-Correction during drafting:
- Correction: Just running a script to delete CSS is dangerous. I need to emphasize the Audit phase. Monday shouldn't be "delete," it should be "identify."
- Correction: Snapshot refreshing can be noisy. It should probably happen after the cleanup, not before.
- Correction: "Tokens" are often global. Changing them affects everything. Tuesday should be "Audit/Plan Token changes," Wednesday "Execute."
Final Polish: Make it punchy. Use emojis for the days. Call it "The Weekly Dust-Busting Schedule."
Let's write it out.
- Monday: The Audit (Static Analysis).
- Tuesday: Token Housekeeping (The Source of Truth).
- Wednesday: CSS Surgery (Removing the Dead Weight).
- Thursday: Storybook Stabilization (Visual Regressions).
- Friday: Integration & Documentation.
Looks solid. I will flesh out the details for each day now. A weekly "UI Hygiene" cadence is an excellent strategy to prevent design debt from accumulating into an unmanageable monolith. The key is to separate Detection (finding issues) from Action (fixing issues) to avoid blocking feature work.
Here is a proposed Weekly UI Hygiene Schedule (The "Scrub & Polish" Cadence).
📅 The Weekly Cycle
Monday: Detection & Audit (The "Dust Sweep")
Goal: Identify the debt without fixing it yet. Generate reports so the team knows what to focus on.
- Run Static Analysis: Execute linters (Stylelint) and formatters (Prettier) in "check" mode.
- Token Audit: Run a script (e.g.,
style-dictionaryor a custom CLI tool) to identify design tokens that are defined in your system but unused in code. - CSS Stats: Generate a
css-statsreport to check for specificity spikes or duplicate selectors. - Output: A "Hygiene Ticket" created in Jira/Linear listing the specific files or tokens causing issues this week.
Tuesday: Token & Variable Pruning (The "Deep Clean")
Goal: Clean up the source of truth (Design Tokens) before cleaning the implementation.
- Deprecation Marking: Instead of deleting tokens immediately, mark unused tokens as
@deprecatedin the code comments or design system documentation. - Variable Consolidation: If Audit Day showed hardcoded hex colors or spacing values, replace them with the correct design token variables.
- Sync: Push the token updates to ensure Figma and the Codebase are aligned.
Wednesday: CSS Surgery (The "Decluttering")
Goal: Remove dead code and refactor unhealthy patterns.
- Dead Code Elimination: Use a tool like PurgeCSS or Uncss (in report mode) to identify CSS classes that exist in stylesheets but are not present in the JS/HTML bundle. Remove them.
- Specificity Squashing: Tackle the top 3 highest-specificity selectors identified on Monday. Refactor IDs to classes, or flatten nesting structures.
- !important Reduction: Target a reduction of
!importantflags by 10-20% through better CSS architecture.
Thursday: Storybook Refresh (The "Polish")
Goal: Ensure the component library is visually accurate and documented.
- Snapshot Updates: Run
npm run test -- -uto update Storybook snapshots that are failing due to legitimate intentional changes. - Interaction Testing: Check that interaction tests (clicks, hovers) still fire correctly after Wednesday's CSS changes.
- Controls Check: Ensure the "Controls" tab in Storybook works for all props (no
undefinedstates where defaults should exist).
Friday: Governance & Merge (The "Inspection")
Goal: Close the loop and merge the work.
- Bundle Size Check: Compare the CSS bundle size before and after the cleanup. Celebrate the kilobytes saved!
- Visual Regression: Run a final visual regression test (e.g., Chromatic or Percy) on the affected components.
- The Merge: Merge the "UI Hygiene" PR.
- Team Retro: A 15-minute chat: "Why did we accumulate this CSS debt this week? How can we write cleaner code next week?"
🛠 Recommended Tool Stack
To make this cadence sustainable, you need automation.
- For Unused CSS:
PurgeCSS,UnCSS, orDead Code Eliminationin Webpack. - For Tokens:
Style-Dictionary(for management) +ts-unused-exports(to find unused JS variables often linked to tokens). - For Quality:
Stylelint(rules:max-specificity,declaration-block-no-duplicate-properties). - For Visuals:
Storybook+Chromatic(orPercy) for automated snapshot diffs.
📝 The "Stop the Bleeding" Protocols
To ensure your Friday cleanup isn't fighting a losing battle, implement these two workflow rules during the week:
- The Snapshot Rule: If a developer updates a component, they must update the Storybook story in the same PR. No exceptions.
- The Token Rule: No hardcoded colors/spacing values. If a PR contains a hardcoded hex code (e.g.,
#FF0000instead ofvar(--color-danger)), the PR is blocked by CI.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.