Skip to content
Skills Library
Design & UX · Learning & explanation

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.

Repository
otter ↗
Licence
BSD-3-Clause
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. Core Rule: Token-First
  2. Token Selection Rules
  3. Fallback Questions
  4. Finding Tokens
  5. Otter Extensions (for token JSON definitions)
  6. Naming Conventions
  7. When NOT to Use Tokens
  8. Stop Rules
Original SKILL.md headings · 77 lines, 482 words
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)…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.