diff options
| author | darekrossman <darek@subpopular.dev> | 2026-10-14 13:58:43 -0400 |
|---|---|---|
| committer | darekrossman <darek@subpopular.dev> | 2026-10-14 13:58:43 -0400 |
| commit | 0441b3dc559d4ceeeaffa2343297bf64c07f23b9 (patch) | |
| tree | a50bef62dd6172c6bad7746526bd1e091402a822 | |
| parent | 57de081beffdbed862802c8e834de1dc78b62cd0 (diff) | |
Make optimize-turbopack-css checks conditional on app traitsadd-optimize-turbopack-css-skill
4 files changed, 65 insertions, 53 deletions
diff --git a/skills/optimize-turbopack-css/SKILL.md b/skills/optimize-turbopack-css/SKILL.md index b7dd979..ea1fb5f 100644 --- a/skills/optimize-turbopack-css/SKILL.md +++ b/skills/optimize-turbopack-css/SKILL.md @@ -27,7 +27,7 @@ Determine whether the user asked for analysis, a plan, or execution. - For planning, return prioritized phases with evidence, expected impact, risks, and acceptance criteria. - For execution, implement one optimization class at a time, verify it, and preserve unrelated worktree changes. - Never weaken the supported-browser contract without explicit authorization. A newer Browserslist is an optimization only when product support permits it. -- Never purge selectors until runtime-generated, CMS, localization, and third-party class names have been inventoried. +- Never purge selectors until class names that the app builds at runtime or receives from outside the repository, such as CMS content, translations, or third-party code, have been inventoried. ## 1. Discover the project @@ -42,6 +42,15 @@ Locate the package containing `next`, then inspect: - SCSS entry points, CSS Modules, shared partials, framework entries, utility generators, and package aliases. - Existing dirty changes. Preserve them and avoid rewriting overlapping files unnecessarily. +Record which of these traits the app has. Later checks for a trait apply only when the app has it: + +- Multiple locales, locale-specific typography, or right-to-left (RTL) documents. +- HTML or class names from outside the repository, such as CMS content, remote templates, or third-party embeds. +- A CSS framework such as Bootstrap, or an in-house utility library. +- Web components or other side-effect client registration. +- Print, email, or PDF output that shares stylesheets. +- Themes such as dark or high-contrast modes. + Classify each stylesheet as one of: 1. Universal global CSS. @@ -116,7 +125,7 @@ Expect this duplication to surface after migration. Webpack's whole-file cssnano ### D. Global framework and utility surface -Measure framework, design-system, theme, reset, CMS, and utility imports independently. Check for overlapping systems such as multiple spacing, color, typography, border, display, or grid utility families. +Measure framework, design-system, theme, reset, utility, and external-content compatibility imports independently. Check for overlapping systems such as multiple spacing, color, typography, border, display, or grid utility families. Use import ablation builds to determine contribution. Do not describe a curated framework entry as a full framework until its imports have been inspected. @@ -152,18 +161,18 @@ Collect class usage from: - Static JSX/TSX/HTML and template strings. - Class composition helpers and dynamically generated names. -- Tests, stories, email/print templates, and server-rendered fragments. -- CMS, commerce, localization, and remote HTML across supported markets. +- Tests, stories, templates, and server-rendered fragments. +- Content from outside the repository, such as CMS entries, remote HTML, translations, and third-party embeds, for every content variant the app serves. - Browser CSS coverage over representative authenticated and anonymous routes. Create an explicit safelist for runtime-only classes. Record the source and owner of each pattern. Coverage reflects only the routes, sessions, and interactions exercised, so treat it as supporting evidence, not proof that a selector is unused. ## 5. Prioritize work by reach and emitted size -Optimize in this order unless measurements contradict it: +Rank each candidate by how many routes load it and how much CSS it emits, and skip categories that don't apply to the app. A typical order is: 1. Universally loaded Cartesian Sass generators. -2. Repeated locale/direction/print selector expansion. +2. Selectors repeated for each locale, direction, theme, or print mode. 3. Overlapping global utility systems. 4. Oversized framework utility maps and global component layers. 5. Selector-emitting shared partials. @@ -184,13 +193,13 @@ For each optimization: 6. Run the validation matrix. 7. Report measured impact and remaining risk before continuing. -Use explicit allowlists for utility generators. Centralize language and direction behavior with inherited CSS variables where possible. Consolidate overlapping utility families. Keep tokens separate from selector-emitting entries. When lowering is required, reduce the rules and selectors that carry one-sided logical declarations. Route-scope CSS only when the route graph supports it. +Use explicit allowlists for utility generators. Where styles vary by locale, direction, or theme, centralize the variation in inherited CSS variables. Consolidate overlapping utility families. Keep tokens separate from selector-emitting entries. When lowering is required, reduce the rules and selectors that carry one-sided logical declarations. Route-scope CSS only when the route graph supports it. Avoid combining browser-target changes, Sass-generator refactors, and stylesheet-boundary changes in one measurement. Separate variables so each result is attributable and reversible. ## 7. Validate and enforce budgets -Validate production builds, representative routes, supported viewports, LTR/RTL computed properties, every supported locale, print, CMS content, CSS ordering, specificity-sensitive utility combinations, error fallbacks, and applied-versus-requested browser CSS. Use the detailed matrix in the validation reference. +Validate production builds, representative routes, supported viewports, CSS ordering, specificity-sensitive utility combinations, error fallbacks, and applied-versus-requested browser CSS. Add locale, RTL, external-content, print, and theme coverage for the traits recorded in step 1. Use the detailed matrix in the validation reference. Introduce CI budgets after the optimized baseline stabilizes. Track both global assets and route payloads. Require an intentional budget update for regressions. @@ -204,7 +213,8 @@ Lead with the root cause and measured outcome. Include: - Before/after route and asset table. - Source files and generators responsible. - Changes implemented or proposed in priority order. -- Compatibility, CMS, RTL, locale, print, and ordering risks. +- App traits recorded in step 1, and checks skipped because a trait is absent. +- Compatibility and ordering risks, plus locale, RTL, external-content, print, and theme risks for the traits the app has. - Routes, sessions, and interactions the browser measurements covered, and any they could not reach. - Verification performed and remaining follow-up. diff --git a/skills/optimize-turbopack-css/references/optimization-patterns.md b/skills/optimize-turbopack-css/references/optimization-patterns.md index 0d757ba..0570de4 100644 --- a/skills/optimize-turbopack-css/references/optimization-patterns.md +++ b/skills/optimize-turbopack-css/references/optimization-patterns.md @@ -39,7 +39,7 @@ Add a Sass snapshot test for the emitted selector set. Require a safelist change ## Centralize language and direction behavior -Do not repeat every locale selector inside every font-size, heading, button, and print utility. +Apply this when the app varies typography or spacing by locale or direction. Do not repeat every locale selector inside every font-size, heading, button, and print utility. Before: @@ -58,12 +58,12 @@ Before: After: ```scss -html:lang(vi) { - --app-font: 'Noto Sans'; +html:lang(ja) { + --app-font: 'Noto Sans JP'; } -html:lang(ta) { - --app-font: 'Noto Sans Tamil'; - --app-text-line-height: 1.4; +html:lang(ar) { + --app-font: 'Noto Sans Arabic'; + --app-text-line-height: 1.6; } body { @@ -76,7 +76,7 @@ body { } ``` -Preserve locale-specific weight and line-height behavior. Verify every supported locale, RTL, and print output. +Preserve locale-specific weight and line-height behavior. Verify every supported locale, plus RTL and print output when the app supports them. ## Group locale selectors by declaration signature @@ -128,7 +128,7 @@ Inventory class families by property, not package name: | Property family | Examples | | --------------- | ------------------------------------------------------------------- | -| Spacing | Bootstrap, design-system spacing, custom logical spacing | +| Spacing | Framework utilities, design-system spacing, custom spacing | | Typography | Framework headings, design-system typography, custom font utilities | | Borders/colors | Framework utilities, palette loops, semantic tokens | | Layout | Grid, display, flex, width, visibility | @@ -137,10 +137,11 @@ Choose one canonical family per use case. Retain compatibility aliases only for Configure a framework utility API instead of generating an overlapping custom copy when possible. -Before deleting a custom logical spacing family, inspect what the replacement -actually emits. Bootstrap start/end utilities can use physical left/right -properties and assume a separate RTLCSS build. Applications that switch `dir` -at runtime with one stylesheet need logical properties: +Before replacing a custom utility family with a framework's, inspect what the +framework actually emits. For example, Bootstrap's start and end utilities use +physical left and right properties and assume a separate RTLCSS build, so an +app that switches `dir` at runtime with one stylesheet must remap them to +logical properties: ```scss @use 'sass:map'; @@ -152,18 +153,18 @@ $utilities: map.set( ); ``` -Apply the same pattern to margin-end and padding start/end before Bootstrap's -utility API emits classes. Verify physical computed values in both LTR and RTL. -Keep custom negative logical margins if the framework does not generate them; -remove invalid negative padding. +Apply the same remap to margin-end and padding start and end before Bootstrap's +utility API emits classes, and verify physical computed values in both LTR and +RTL. Keep custom utilities the framework doesn't generate, such as negative +logical margins. -## Curate Bootstrap and other frameworks +## Curate CSS framework entries -Inspect the actual Sass entry before labeling it "full Bootstrap." Measure each import independently. +Inspect the actual Sass entry before describing it as the full framework. Measure each import independently. -Retain required configuration dependencies in their documented order, then include only required layout, component, helper, and utility entries. Restrict the Bootstrap `$utilities` map and its responsive variants using the class inventory. +Retain required configuration dependencies in their documented order, then include only required layout, component, helper, and utility entries. Restrict the framework's utility configuration, such as Bootstrap's `$utilities` map, and its responsive variants using the class inventory. -Verify dynamic framework classes from CMS or third-party components before removal. +Verify dynamic framework classes from external content or third-party components before removal. ## Separate universal and route-owned CSS @@ -196,11 +197,11 @@ each graph change. Next.js 16 removed First Load JS from `next build` output, so use `next experimental-analyze` (16.1+) or a bundle analyzer for the JavaScript plane. Improvements on one plane do not guarantee improvements on all three. -## Protect runtime and CMS content +## Protect runtime and external content -Collect classes from remote HTML, commerce templates, CMS records, localization, emails, and feature flags. Maintain a reviewed safelist with source, owner, and expiration criteria. +Collect classes from every source the app renders outside its own components, such as CMS records, remote HTML, templates, translations, emails, and feature flags. Maintain a reviewed safelist with source, owner, and expiration criteria. -Do not use blanket PurgeCSS against an application that renders remote or dynamically constructed class names. If a purge stage is explicitly authorized, run it only with a tested extractor and safelist, and compare rendered content across representative markets. +Do not use blanket PurgeCSS against an application that renders remote or dynamically constructed class names. If a purge stage is explicitly authorized, run it only with a tested extractor and safelist, and compare rendered content across representative content variants. ## Optimize CSS Modules after global CSS diff --git a/skills/optimize-turbopack-css/references/runtime-delivery.md b/skills/optimize-turbopack-css/references/runtime-delivery.md index 218ef57..28b6335 100644 --- a/skills/optimize-turbopack-css/references/runtime-delivery.md +++ b/skills/optimize-turbopack-css/references/runtime-delivery.md @@ -161,10 +161,9 @@ When successful routes request unrelated CSS, inspect: 5. Route prefetching and framework fallbacks. Hovering over or prefetching a `<Link>` preloads the target route's CSS. -Keep last-resort error UI self-contained. Avoid importing the normal design -system, translation/action stack, image abstraction, sanitizer, or shared error -component when native HTML, a small CSS Module, and text rendering meet the -fallback contract. +Keep last-resort error UI self-contained. Avoid importing the full design +system, app-wide providers, or shared components when native HTML, a small CSS +Module, and plain text meet the fallback contract. Global-error, not-found, error, and loading CSS attach to successful routes under webpack too, and a Next.js maintainer describes the not-found preload as diff --git a/skills/optimize-turbopack-css/references/validation.md b/skills/optimize-turbopack-css/references/validation.md index da3f70a..97f5b6a 100644 --- a/skills/optimize-turbopack-css/references/validation.md +++ b/skills/optimize-turbopack-css/references/validation.md @@ -1,6 +1,6 @@ # Validation and rollout matrix -Use this matrix for executed optimizations. Tailor it to the product's supported routes, locales, browsers, and content systems. +Use this matrix for executed optimizations. Tailor it to the product's supported routes and browsers, and include locale, RTL, external-content, print, and theme checks only for traits the app has. ## Build validation @@ -41,8 +41,8 @@ Cover at least: - Small mobile, large mobile, tablet, desktop, and wide desktop. - Every custom Sass breakpoint. -- LTR and RTL documents. -- Every locale with a special font, line height, weight, or glyph requirement. +- LTR and RTL documents when the app supports RTL. +- Every supported locale with a special font, line height, weight, or glyph requirement. - Print preview and generated PDF/email output when styles are shared. - Light/dark/high-contrast themes when supported. - Loading, error, disabled, focus, hover, selected, and expanded states. @@ -56,7 +56,8 @@ Prefer screenshot diffing for stable routes. Review cascade and stylesheet order ## Runtime content coverage -- Snapshot representative CMS and remote HTML across markets and dealers. +- Snapshot representative CMS and remote HTML for each content variant the app + serves, such as regions, tenants, or brands. - Exercise dynamically constructed utility classes. - Test authenticated and anonymous route variants, with a saved test-account session for each role that changes the rendered UI. @@ -65,8 +66,8 @@ Prefer screenshot diffing for stable routes. Review cascade and stylesheet order - When `experimental.inlineCss` is enabled, confirm each prerendered page embeds each stylesheet once. - Force the root error boundary and verify its content, accessibility, and CSS dependency set. -- Inspect utility or framework-only routes that should not inherit application - component registration. +- Check that lightweight routes, such as embeds or framework-only pages, don't + inherit app-wide providers or component registration. - Treat browser CSS coverage as evidence only; do not use it as the sole deletion criterion. ## Sass contract tests @@ -74,9 +75,9 @@ Prefer screenshot diffing for stable routes. Review cascade and stylesheet order - Compile token-only partials and assert zero emitted CSS. - Snapshot selectors from allowlisted utility generators. - Assert removed Cartesian combinations stay absent. -- Assert required CMS/runtime selectors remain. -- Assert language and RTL variables resolve for every supported case. -- Compare selector-to-declaration maps when grouping language selectors. +- Assert selectors required by runtime or external content remain. +- When styles vary by locale or direction, assert the variables resolve for every supported case. +- Compare selector-to-declaration maps when grouping locale selectors. - Snapshot lowered output for representative logical-property rules at the production targets, and assert that no rule from a split selector list is dropped. Open Lightning CSS issues report dropped rules. - Enforce maximum compiled byte sizes for the largest generators. - Guard source boundaries that must remain token-only or dependency-light. @@ -87,13 +88,13 @@ Use small, reversible changes: 1. Measurement tooling and safelist. 2. Browser-target correction, only if authorized. -3. Locale/direction generator reduction. -4. Border/color/spacing generator reduction. -5. Framework utility-map reduction. -6. Global-to-route scoping. -7. Root error, client barrel, and side-effect graph isolation. -8. CSS Module cleanup. -9. CI budget enforcement. +3. Sass generator reduction, starting with the generators that emit the most + CSS on the most routes. +4. Framework utility-map and overlapping utility-system reduction. +5. Global-to-route scoping. +6. Root error, client barrel, and side-effect graph isolation. +7. CSS Module cleanup. +8. CI budget enforcement. Rebuild and remeasure after every step. Avoid batching unrelated phases. @@ -107,7 +108,8 @@ Define project-specific numbers before implementation. A complete optimization n - No unexplained visual diffs remain. - Manifest-attributed and browser-requested CSS differences are explained and any residual transient preloads are recorded. -- CMS, RTL, locale, print, and third-party coverage passes. +- Coverage passes for every trait the app has, such as external content, RTL, + locales, print, themes, and third-party widgets. - Production Turbopack build succeeds. - Webpack fallback remains documented for Next.js 15 when required. - Changes are divided into commits or PRs that can be reverted independently. |
