styling-best-practices
/styling-best-practices
This skill should be used when developing UI components, writing CSS/SCSS styles, or when the user asks about design tokens, theming, CSS custom properties, or styling conventions. Guides token-first development and Otter extensions usage.
- Author
- amadeusitgroup ↗
- Repository
- otter ↗
- Licence
- BSD-3-Clause
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
BSD-3-Clause, otwarta.
What it does and when to use it
This skill should be used when developing UI components, writing CSS/SCSS styles, or when the user asks about design tokens, theming, CSS custom properties, or styling conventions. Guides token-first development and Otter extensions usage.
Original author description
This skill should be used when developing UI components, writing CSS/SCSS styles, or when the user asks about design tokens, theming, CSS custom properties, or styling conventions. Guides token-first development and Otter extensions usage.
How it works
- Core Rule: Token-First
- Token Selection Rules
- Fallback Questions
- Finding Tokens
- Otter Extensions (for token JSON definitions)
- Naming Conventions
- When NOT to Use Tokens
- Stop Rules
SKILL.md preview
---
name: styling-best-practices
description: This skill should be used when developing UI components, writing CSS/SCSS styles, or when the user asks about design tokens, theming, CSS custom properties, or styling conventions. Guides token-first development and Otter extensions usage.
---
# Styling Best Practices
## Core Rule: Token-First
**ALWAYS use design tokens (CSS custom properties) instead of hardcoded values** for colors, spacing, typography, border-radius, shadows, and animation durations.
### Decision Rules
1. Use the `find_design_token` MCP tool to discover available tokens.
2. Apply the following decision tree:
- If token found → recommend it and explain why.
- If multiple tokens match → ask the user to choose.
- If no token matches → ask for more precise intent or broader context.
- If only a primitive matches → prefer a semantic token / ask whether a semantic alias should be created.
## Token Selection Rules
- If an exact component token exists, use it.
- Else if a semantic token exists, use it.
- Else if only a primitive token exists, use it only as a fallback and mention that a semantic token would be better.
- Else ask the user for clarification.
## Fallback Questions
Ask for:
- the visual intent (color, spacing, size, radius, shadow, etc.)
- the semantic meaning (primary, success, danger, neutral, etc.)
- the expected scope (component-specific or global)
- whether a primitive fallback is acceptable
```scss
/* ❌ BAD */
.card { background: #ffffff; padding: 16px; border-radius: 8px; }
/* ✅ GOOD */
.card { background: var(--colors-surface); padding: var(--spacing-md); border-radius: var(--shape-corner-medium); }
```
## Finding Tokens
Use `find_design_token` with the CSS property and a semantic description of the need.
If no results, try broader terms or use `list_design_tokens` to browse by category.
## Otter Extensions (for token JSON definitions)
| Extension | Purpose | Example |
|-----------|---------|---------|
| `o3rPrivate: true` | Internal token, not exposed to CMS | Implementation details |
| `o3rScope: '<selector>'` | Scope CSS property to a selector instead of `:root` | Component-specific tokens |
| `o3rExpectOverride: true` | Token designed to be overridden (theming/rules engine) | Brand colors |
| `o3rImportant: true` | Generates with `!important` (use sparingly) | Legacy CSS specificity battles |
| `o3rUnit: '<unit>'` | Converts unitless value to a CSS unit (`px`, `rem`, `em`, `%`, `vw`, `vh`, `ms`, `s`) | Figma-extracted raw numbers |
| `o3rRatio: <number>` | Applies a multiplier to numeric value | Derived spacing/type scales |
| `o3rMetadata: {...}` | CMS metadata (tags, label, category, component) | Design system portal discoverability |
## Naming Conventions
- **kebab-case**: `colors-primary`, not `colorsPrimary`
- **Structure**: `{category}-{subcategory}-{variant}-{state}`
- **Categories**: `colors-*`, `spacing-*`, `typography-*`, `shape-*`, `elevation-*`, `motion-*`
- **Semantic names**: `colors-primary`, not `blue-500`; `spacing-md`, not `size-3`
## When NOT to Use Tokens
Skip tokens for: one-off layout values, z-index layering, `@keyframes` intermediate values, structural CSS (`display`, `position`, `overflow`), content-coupled dimensions (`max-width: 65ch`).
## Stop Rules
Halt and ask for clarification if:
- No matching token exists for a needed value
- A hardcoded color/spacing is being used where tokens are available
- A primitive token is used where a semantic alternative exists
- A new token needs to be created
Versions
The database has no other skills named styling-best-practices.
Database snapshot: 13.11.2026 · package version df5fec242d15 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 82design-system
Generate, extract or audit the project's design tokens: writes or lints .desk/DESIGN.md and exports CSS custom properties or a Tailwind theme. Use when a project needs its tokens made, pulled out of existing code, or checked for drift. - 100jaspr-styling
Write type-safe CSS-in-Dart to style Jaspr components. Use this skill when styling components, implementing themes, or using CSS properties. - 100design-systems
Design system architecture and design tokens. Covers W3C Design Token spec, atomic design methodology, component documentation, theming, dark/light mode, and modern CSS custom property patterns. USE WHEN: user mentions "design system", "design tokens", "component library",… - 100tailwind-patterns
Tailwind CSS v4 patterns, component styling, dark mode, responsive design, and design system integration. Use when styling components or reviewing CSS. - 100design-build
Implement or refine frontend visual design, CSS, layout, typography, color tokens, and component states. Use when creating or styling an interface. - 100tokens
Audit the repo's styling for raw colours, sizes, spacing and fonts, then define design tokens with the user (primitives, semantic tokens, light and dark) in one W3C Design Tokens 2025.10 source that builds into the repo's own styling (CSS variables, Tailwind 4 or 3, SCSS, TS)…