fundamental-styles: Skill for Claude Code

SCSS Coding Standards for fundamental-styles

When to use this skill:

• Writing new SCSS component files
• Refactoring existing SCSS code
• Reviewing SCSS changes
• Questions about fundamental-styles CSS architecture

1. Architecture & Methodology

BEM (Block Element Modifier) Pattern

Structure:

$block: #{$fd-namespace}-component-name;

.#{$block} {
    // Block styles

    &__element {
        // Element styles
    }

    &--modifier {
        // Modifier styles
    }
}

Naming convention:

• Block: .fd-{component} (e.g., .fd-card, .fd-button)
• Element: .fd-{component}__{element} (e.g., .fd-card__header, .fd-button__text)
• Modifier: .fd-{component}--{modifier} (e.g., .fd-card--interactive, .fd-button--emphasized)

Rules:

• Use strict BEM - no deviations
• Block variable format: $block: #{$fd-namespace}-component-name;
• Use Sass nesting with & for elements and modifiers
• The ampersand creates single-level class selectors, not nested ones

Self-Contained Components

Each component must be completely independent:

✅ DO:

// In card.scss
.#{$block} {
    &__content {
        // Style card content
    }
}

❌ DON'T:

// In card.scss - WRONG!
.#{$block} {
    .#{$fd-namespace}-button {
        // Never style other components!
        color: red;
    }
}

If you need to adjust a child component:

• Create a specific modifier class for that component
• Example: Instead of .fd-card .fd-button { }, create .fd-button--in-card { }
• Document the relationship in both component files

Why this matters:

• Prevents global style bleeding
• Eliminates package version conflicts
• Components render correctly in isolation
• No unexpected side effects

2. File Structure & Imports

Standard file header:

@use 'sass:map'; // Only when using Sass maps

@import './new-settings'; // or component-specific variables file
@import './mixins';

$block: #{$fd-namespace}-component-name;
$other-component: #{$fd-namespace}-other-component; // If referencing classes

// Component-specific variables/maps here
$fd-component-sizes: (
    's': (
        ...
    ),
    'm': (
        ...
    )
);

.#{$block} {
    // Component styles
}