Scss Dry Structure

SCSS DRY Structure

Create cohesive interfaces with clear style ownership, meaningful shared values, and economical CSS. SCSS is a useful authoring tool; the outcome is a well-designed, maintainable interface.

Decide whether this fits

Consider the whole project before adopting this workflow: its styling system, design system, build pipeline, and the requested change. The presence of a CSS file alone is not a reason to use this skill.

• Good fit: substantial component work in a Sass project; consolidating inconsistent tokens or repeated style patterns; an explicit request for SCSS or styling architecture.
• Usually skip: a small spacing/color fix, content-only work, native UI code, or ordinary work in an established Tailwind, CSS-in-JS, CSS Modules, or framework-scoped styling system. Continue with that project's normal workflow without a skill audit.
• Explicit invocation: apply the relevant principles even in plain CSS or another system, adapting to its conventions. Invocation does not require converting it to Sass.

The user's instructions take precedence over this skill's defaults. Infer routine choices from the project and proceed; ask only when missing information materially changes the result. Keep work proportionate to the request. Do not expand a component change into a redesign, tooling migration, or design-system rebuild.

Establish the local context

Inspect the relevant component/template, nearby styles, token definitions, and actual style imports/build configuration. Identify the source file, selector contract, theme/state hooks, and browser targets. Follow a shared token's consumers when changing its meaning; a local search cannot establish its global impact.

For an unfamiliar or scattered style tree, optionally run the bundled inventory from this skill's directory:

shCopy code
python3 /path/to/scss-dry-structure/scripts/style_audit.py /path/to/project-or-component

Replace paths with the actual skill and project locations. The script is a bounded, read-only source inventory, not a CSS parser or proof of quality. Narrow the path when its output is incomplete. If unavailable, use targeted file searches and continue. Do not run it or load every reference for a routine edit.

Make the design intentional

For new or substantially redesigned UI, identify the audience, primary action, content hierarchy, and visual direction from the brief and existing assets. Carry the project's typography, spacing rhythm, color roles, imagery, and density through the affected components. If the brief leaves room, choose a coherent direction and implement it without a mandatory design questionnaire.

Use composition and hierarchy to distinguish sections. Cards, gradients, shadows, pills, and animation should serve the content. Build with realistic content and relevant empty, error, loading, and interaction states. Read design-quality.md for substantial visual work.

Author with clear ownership

• Extend the appropriate partial or component stylesheet; wire new files into the actual import graph. Preserve CMS/plugin hooks, naming conventions, and existing layer precedence. Edit source styles and rebuild tracked outputs through the existing pipeline.
• Reuse tokens by meaning, not coincidentally equal values. Prefer CSS custom properties for runtime themes and component variation, Sass variables/functions for compile-time work. Keep one source of truth; a token for every literal or an alias for every component adds noise.
• Share styles when they represent a stable common responsibility. Prefer an existing component or composition pattern; use a mixin for useful parameterized behavior. Small intentional duplication can be cheaper than coupling unrelated components. Avoid new @extend chains or large generated utility maps merely to satisfy DRY.
• Keep compiled selectors predictable and low in specificity. Nest for component parts, states, and related queries, not to mirror the DOM. Preserve local BEM/scoping conventions; Sass &__part concatenation is not native CSS nesting syntax.
• For new Sass modules, use namespaced @use/@forward and built-in modules. Keep @use at the top level before style rules; never nest it in @layer. Preserve working legacy import paths for bounded edits; migrate them when that is part of the task.
• Prefer intrinsic Grid/Flex layouts, flexible sizing, and content-driven breakpoints. Use container queries when a component responds to its allocated space. Choose features for the project's browser targets, providing a usable fallback when needed.

Read scss-patterns.md when choosing token/module boundaries, resolving cascade issues, or changing architecture. It contains a compilable layer pattern and important Sass/CSS distinctions.

Verify the result, then finish

Use the project's relevant build/lint checks. For visible changes, inspect the affected UI at narrow and wide sizes when a browser is available; check keyboard focus, contrast, overflow, content extremes, and changed states. Fix observed defects. If rendering is unavailable, state that limitation.

For shared-style or substantial UI changes, use validation.md to select additional accessibility, regression, and performance checks. Inspect emitted CSS when changing imports, layers, mixins, or generation. Avoid new runtime dependencies for CSS-solvable layout or decoration.

Scale checks to the changed surface and complete required project checks. Once they pass, broaden testing only for unresolved risks or new failures. Report the useful design/structure decisions, checks actually run, and material limitations concisely; do not claim performance or accessibility results that were not measured.