SCSS Module
Create or update design system foundation modules in core and theme packages.
When to use
When the user asks to:
- Add a new spacing token (e.g., "add a spacing step of 2.5rem")
- Add or change a color constant or palette entry
- Update typography tokens (font family, size, weight, line height)
- Add or modify elevation levels (box-shadow scale)
- Change border-radius scale values
- Update motion/animation timing or easing
- Add or change z-index layers
Not for component-level SCSS (use manage-scss-variables for component variables, manage-scss-styles for component layout/theme/wiring).
Module inventory
| Module |
Core path |
Purpose |
| spacing |
packages/core/scss/spacing/index.scss |
$default-spacing map — spacing tokens (k-spacing() function) |
| color-system |
packages/core/scss/color-system/ |
Color constants, palettes, swatches, and functions (k-color()) |
| typography |
packages/core/scss/typography/index.scss |
Font families, sizes, weights, line heights |
| elevation |
packages/core/scss/elevation/index.scss |
Box-shadow scale (k-elevation() function) |
| border-radii |
packages/core/scss/border-radii/index.scss |
Border-radius scale (k-border-radius() function) |
| motion |
packages/core/scss/motion/index.scss |
Animation timing, easing, and duration tokens |
| z-index |
packages/core/scss/z-index/index.scss |
Stacking order layers |
Theme re-exports
Each theme re-exports core modules via packages/{theme}/scss/core/. Theme-specific overrides are placed in the corresponding packages/{theme}/scss/core/{module}/ directory.
Inputs
| Input |
Required |
Description |
| Module |
Yes |
Which module: spacing, color-system, typography, elevation, border-radii, motion, z-index |
| Changes |
Yes |
What to add, change, or remove |
| Target themes |
No |
Themes to update if theme-level overrides are needed. Usually changes are core-only. |
Procedure
Step 1: Read the current module
Read the module's files in packages/core/scss/{module}/ to understand the current structure and conventions. Pay attention to:
- How tokens are defined (maps, variables, constants)
- SassDoc documentation patterns
- The function API (e.g.,
k-spacing(), k-color(), k-elevation())
Step 2: Apply changes to core
Edit the appropriate file in packages/core/scss/{module}/.
Rules:
- Follow the existing naming and documentation patterns in the module
- Add SassDoc
/// comments with @group annotations
- Maintain the ordering convention (e.g., spacing values are ordered by size)
- For
color-system, respect the multi-file structure: constants in _constants.scss, palettes in _palettes.scss, functions in _functions.scss
Step 3: Apply theme overrides (if needed)
Most design system changes are core-only — themes inherit via packages/{theme}/scss/core/. Only edit theme-specific files when:
- A theme needs a different token value (e.g., Material uses different elevation shadows)
- A theme adds theme-specific tokens not in core
- The swatch configuration (
lib/swatches/) needs updating
Step 4: Validate
npm run lint:styles 2>&1
npm run sass 2>&1
If the change affects token functions used by components, also verify:
npm run docs 2>&1
npm run test:units 2>&1
Gotchas
- Core modules are foundational — changes here affect every component and every theme. Be conservative.
- Spacing map keys are not arbitrary — the
$default-spacing map uses a scale (0, 0.5, 1, 1.5, 2...). New keys must fit the scale.
- Color constants vs swatch colors —
_constants.scss has immutable color values (white, black). Swatch-specific colors go in _swatch.scss or theme overrides.
- Theme core re-exports —
packages/{theme}/scss/core/_index.scss barrels all core modules. If you add a new sub-module, it needs to be forwarded there.
- Function API stability —
k-spacing(), k-color(), k-elevation(), k-border-radius() are used by hundreds of component files. Don't change function signatures.
1---2name: manage-scss-modules3description: Create or update design system foundation modules — spacing, color-system, typography, elevation, border-radii, motion, and z-index. These modules live in packages/core/scss/ and are re-exported by each theme via packages/{theme}/scss/core/. Use this skill when the user wants to add a spacing token, color constant, font size, elevation level, border-radius scale value, or animation timing.4---56# SCSS Module78Create or update design system foundation modules in core and theme packages.910## When to use1112When the user asks to:13- Add a new spacing token (e.g., "add a spacing step of 2.5rem")14- Add or change a color constant or palette entry15- Update typography tokens (font family, size, weight, line height)16- Add or modify elevation levels (box-shadow scale)17- Change border-radius scale values18- Update motion/animation timing or easing19- Add or change z-index layers2021Not for component-level SCSS (use `manage-scss-variables` for component variables, `manage-scss-styles` for component layout/theme/wiring).2223## Module inventory2425| Module | Core path | Purpose |26|--------|-----------|---------|27| **spacing** | `packages/core/scss/spacing/index.scss` | `$default-spacing` map — spacing tokens (`k-spacing()` function) |28| **color-system** | `packages/core/scss/color-system/` | Color constants, palettes, swatches, and functions (`k-color()`) |29| **typography** | `packages/core/scss/typography/index.scss` | Font families, sizes, weights, line heights |30| **elevation** | `packages/core/scss/elevation/index.scss` | Box-shadow scale (`k-elevation()` function) |31| **border-radii** | `packages/core/scss/border-radii/index.scss` | Border-radius scale (`k-border-radius()` function) |32| **motion** | `packages/core/scss/motion/index.scss` | Animation timing, easing, and duration tokens |33| **z-index** | `packages/core/scss/z-index/index.scss` | Stacking order layers |3435### Theme re-exports3637Each theme re-exports core modules via `packages/{theme}/scss/core/`. Theme-specific overrides are placed in the corresponding `packages/{theme}/scss/core/{module}/` directory.3839## Inputs4041| Input | Required | Description |42|-------|----------|-------------|43| **Module** | Yes | Which module: `spacing`, `color-system`, `typography`, `elevation`, `border-radii`, `motion`, `z-index` |44| **Changes** | Yes | What to add, change, or remove |45| **Target themes** | No | Themes to update if theme-level overrides are needed. Usually changes are core-only. |4647## Procedure4849### Step 1: Read the current module5051Read the module's files in `packages/core/scss/{module}/` to understand the current structure and conventions. Pay attention to:52- How tokens are defined (maps, variables, constants)53- SassDoc documentation patterns54- The function API (e.g., `k-spacing()`, `k-color()`, `k-elevation()`)5556### Step 2: Apply changes to core5758Edit the appropriate file in `packages/core/scss/{module}/`.5960**Rules:**61- Follow the existing naming and documentation patterns in the module62- Add SassDoc `///` comments with `@group` annotations63- Maintain the ordering convention (e.g., spacing values are ordered by size)64- For `color-system`, respect the multi-file structure: constants in `_constants.scss`, palettes in `_palettes.scss`, functions in `_functions.scss`6566### Step 3: Apply theme overrides (if needed)6768Most design system changes are core-only — themes inherit via `packages/{theme}/scss/core/`. Only edit theme-specific files when:69- A theme needs a **different token value** (e.g., Material uses different elevation shadows)70- A theme adds **theme-specific tokens** not in core71- The swatch configuration (`lib/swatches/`) needs updating7273### Step 4: Validate7475```bash76npm run lint:styles 2>&177npm run sass 2>&178```7980If the change affects token functions used by components, also verify:8182```bash83npm run docs 2>&184npm run test:units 2>&185```8687## Gotchas8889- **Core modules are foundational** — changes here affect every component and every theme. Be conservative.90- **Spacing map keys are not arbitrary** — the `$default-spacing` map uses a scale (0, 0.5, 1, 1.5, 2...). New keys must fit the scale.91- **Color constants vs swatch colors** — `_constants.scss` has immutable color values (white, black). Swatch-specific colors go in `_swatch.scss` or theme overrides.92- **Theme core re-exports** — `packages/{theme}/scss/core/_index.scss` barrels all core modules. If you add a new sub-module, it needs to be forwarded there.93- **Function API stability** — `k-spacing()`, `k-color()`, `k-elevation()`, `k-border-radius()` are used by hundreds of component files. Don't change function signatures.
telerik