StyleKit

A modular SCSS design system with utilities, colors, typography, and animations

Overview

StyleKit is a comprehensive, modular SCSS design system that provides a consistent foundation for building modern web applications. It includes a complete set of design tokens, utility classes, typography scales, color palettes, spacing systems, and animations. Built with CSS Modules support, StyleKit ensures style encapsulation while maintaining flexibility for customization.

Unlike Tailwind or Bootstrap, StyleKit focuses on developer-centric architecture rather than being a rigid framework or library. I would encourage you to use StyleKit as a starting point for your own design system, and then customize it to fit your needs.

System Requirements

Requirement
Details
Package Manager
npm, yarn, or pnpm
SCSS Processor
sass >= 1.50.0
Module System
CSS Modules support
Framework
Framework agnostic (React, Vue, Angular, etc.)

Installation

Install StyleKit from npm:

bash
npm install @san-siva/stylekit

Or using yarn:

bash
yarn add @san-siva/stylekit

Module Structure

StyleKit is organized into specialized modules, each handling a specific aspect of your design system:

Module
Purpose
Key Features
colors.module.scss
Color palette and variables
Primary, secondary, accent, grey scale, semantic colors
typography.module.scss
Font families, sizes, and weights
Type scale, font families, line heights, utility classes
utils.module.scss
Spacing and utility functions
rem/em functions, spacing scale, margin/padding utilities
dimensions.module.scss
Layout dimensions and breakpoints
Container styles, page layout, border radius, responsive breakpoints
animations.module.scss
Animation keyframes
Loading, fade, and movement animations
globals.scss
Global styles and resets
Base styles, resets, global defaults

Usage Patterns

Import All Modules

Import the main module to access all design tokens and utilities:

scss
@use '@san-siva/stylekit/styles/index.module.scss' as stylekit;

.my-component {
  color: stylekit.$color--primary;
  padding: stylekit.space(2);
  font-size: stylekit.$font-size--h3;
}

Import Specific Modules

For better performance and explicit dependencies, import only what you need:

scss
@use '@san-siva/stylekit/styles/colors.module.scss' as colors;
@use '@san-siva/stylekit/styles/utils.module.scss' as utils;

.card {
  background-color: colors.$color--base;
  border: 1px solid colors.$color--border;
  padding: utils.space(3);
  border-radius: utils.rem(8);
}

Use Utility Classes

Import utility classes in your component or globally:

tsx
import styles from '@san-siva/stylekit/styles/index.module.scss';

export function MyComponent() {
  return (
    <div className={styles['margin-bottom--3']}>
      <h1 className={styles['font-size--h1']}>Title</h1>
      <p className={styles['margin-top--2']}>Content</p>
    </div>
  );
}

Colors Module

Provides a comprehensive color palette with semantic naming and variants.

Category
Variables
Description
Primary
$color--primary, $color--primary-light, $color--primary-lighter
Main brand color and variants
Accent
$color--primary-accent, $color--primary-accent-light, $color--primary-accent-lighter
Accent color for highlights and emphasis
Secondary
$color--secondary, $color--secondary-light, $color--secondary-lighter
Secondary brand color and variants
Base
$color--base, $color--surface, $color--code
Background and surface colors
Grey Scale
$color--grey-light, $color--grey-medium, $color--grey-dark, $color--grey-darker
Neutral colors for text and borders
Semantic
$color--error, $color--error-light, $color--link
Semantic colors for states and actions
Variable
Preview
$color--primary
#4242fa
$color--primary-light
rgba(66, 66, 250, 0.05)
$color--primary-lighter
rgba(66, 66, 250, 0.02)
$color--primary-accent
#fed600
$color--primary-accent-light
#fef1c4
$color--primary-accent-lighter
#fef8e0
$color--secondary
#3dad84
$color--secondary-light
#ecf7f3
$color--secondary-lighter
#f2f9f7
$color--base
#ffffff
$color--surface
#f6f6f6
$color--code
#e8f1fc
$color--grey-light
#e1e5e9
$color--grey-medium
#c6c6c7
$color--grey-dark
#6b7c93
$color--grey-darker
#4f5969
$color--error
#ff4232
$color--error-light
#ffecea
$color--link
#0d6efd
$color--dark
#313030
$color--black
#000

Example usage:

scss
@use '@san-siva/stylekit/styles/colors.module.scss' as colors;

.button--primary {
  background-color: colors.$color--primary;
  color: colors.$color--base;

  &:hover {
    background-color: colors.$color--primary-light;
  }
}

.alert--error {
  background-color: colors.$color--error-light;
  border-left: 3px solid colors.$color--error;
  color: colors.$color--dark;
}

Typography Module

Defines a consistent typographic scale with font families, sizes, weights, and line heights.

Font Families:

Variable
Value
Use Case
$font-family--primary
'Rubik', sans-serif
Primary UI text
$font-family--secondary
'Montserrat', sans-serif
Headings and emphasis
$font-family--code
'JetBrains Mono', monospace
Code blocks and technical content
Variable
Preview
Rubik
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Montserrat
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
JetBrains Mono
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Font Sizes:

Variable
Size
Utility Class
$font-size--very-large
64px (4rem)
.font-size--very-large
$font-size--large
48px (3rem)
.font-size--large
$font-size--h1
36px (2.25rem)
.font-size--h1
$font-size--h2
32px (2rem)
.font-size--h2
$font-size--h3
28px (1.75rem)
.font-size--h3
$font-size--h4
24px (1.5rem)
.font-size--h4
$font-size--h5
21px (1.3125rem)
.font-size--h5
$font-size--h6
18px (1.125rem)
.font-size--h6
$font-size--p
16px (1rem)
.font-size--p
$font-size--small
12px (0.75rem)
.font-size--small
Variable
Preview
64px (very-large)
Lorem ipsum dolor sit amet
48px (large)
Lorem ipsum dolor sit amet
36px (h1)
Lorem ipsum dolor sit amet
32px (h2)
Lorem ipsum dolor sit amet
28px (h3)
Lorem ipsum dolor sit amet
24px (h4)
Lorem ipsum dolor sit amet
21px (h5)
Lorem ipsum dolor sit amet
18px (h6)
Lorem ipsum dolor sit amet
16px (p)
Lorem ipsum dolor sit amet
12px (small)
Lorem ipsum dolor sit amet

Font Weights:

Variable
Weight
Utility Class
$font-weight--400
400 (Regular)
.font-weight--400
$font-weight--500
500 (Medium)
.font-weight--500
$font-weight--600
600 (Semi-Bold)
.font-weight--600
$font-weight--700
700 (Bold)
.font-weight--700
$font-weight--800
800 (Extra-Bold)
.font-weight--800
Variable
Preview
400 (Regular)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
500 (Medium)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
600 (Semi-Bold)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
700 (Bold)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
800 (Extra-Bold)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Line Heights:

Variable
Value
Use Case
$line-height--large
1.9
Loose spacing for readability
$line-height--normal
1.6
Standard paragraph text
$line-height--small
1.4
Compact headings
$line-height--very-small
1.2
Very compact text

Example usage:

scss
@use '@san-siva/stylekit/styles/typography.module.scss' as type;

.heading {
  font-family: type.$font-family--secondary;
  font-size: type.$font-size--h2;
  font-weight: type.$font-weight--700;
  line-height: type.$line-height--small;
}

.body-text {
  font-family: type.$font-family--primary;
  font-size: type.$font-size--p;
  line-height: type.$line-height--normal;
}

Using utility classes in React/JSX:

tsx
import styles from '@san-siva/stylekit/styles/typography.module.scss';

<h1 className={`${styles['font-size--h1']} ${styles['font-weight--700']}`}>
  Welcome
</h1>

Utils Module

Provides utility functions and a comprehensive spacing system.

Utility Functions:

Function
Parameters
Description
rem($px)
Number (unitless)
Converts pixels to rem units (16px base)
em($px)
Number (unitless)
Converts pixels to em units (16px base)
space($n, $useEm)
Number (0-9), Boolean
Returns spacing value from scale

Spacing Scale:

Key
Value (px)
Value (rem)
Use Case
0
4px
0.25rem
Micro spacing
1
8px
0.5rem
Tight spacing
2
16px
1rem
Default spacing
3
24px
1.5rem
Medium spacing
4
32px
2rem
Large spacing
5
40px
2.5rem
Extra large spacing
6
48px
3rem
Section spacing
7
56px
3.5rem
Large section spacing
8
64px
4rem
Major section spacing
9
96px
6rem
Page section spacing

Spacing Utility Classes:

Auto-generated margin and padding utilities for all sides (top, bottom, left, right):

text
.margin-top--0 through .margin-top--9
.margin-bottom--0 through .margin-bottom--9
.margin-left--0 through .margin-left--9
.margin-right--0 through .margin-right--9

.padding-top--0 through .padding-top--9
.padding-bottom--0 through .padding-bottom--9
.padding-left--0 through .padding-left--9
.padding-right--0 through .padding-right--9

All spacing utility classes are also available with !important modifiers to override other styles when needed.

Example usage with functions:

scss
@use '@san-siva/stylekit/styles/utils.module.scss' as utils;

.card {
  padding: utils.space(3);        // 24px (1.5rem)
  margin-bottom: utils.space(4);  // 32px (2rem)
  border-radius: utils.rem(8);    // 0.5rem

  .card-header {
    margin-bottom: utils.space(2); // 16px (1rem)
    font-size: utils.rem(20);       // 1.25rem
  }
}

Example usage with utility classes:

tsx
import styles from '@san-siva/stylekit/styles/utils.module.scss';

<div className={styles['padding-top--4']}>
  <h2 className={styles['margin-bottom--2']}>Section Title</h2>
  <p className={styles['margin-bottom--3']}>Content here</p>
</div>

Animations Module

Provides pre-built keyframe animations for common UI patterns.

Animation
Duration
Description
loading_animation
4s linear infinite
Background position animation for loading states
MoveInTop
Custom
Slide in from bottom with fade (200px translateY)
fadeInDown
Custom
Fade in while moving down (20px translateY)
fadeUp
Custom
Fade in while moving up with horizontal offset

Example usage:

scss
@use '@san-siva/stylekit/styles/animations.module.scss';

.modal-enter {
  animation: MoveInTop 0.3s ease-out;
}

.notification {
  animation: fadeInDown 0.4s ease-out;
}

.loading-bar {
  animation: loading_animation 4s linear infinite;
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
  background-size: 200% 100%;
}

Dimensions Module

Defines layout containers, page structures, border radius values, and responsive breakpoints.

Container System:

scss
.container {
  display: flex;
  flex-direction: column;
  justify-content: flex-start;
  padding: 18px;
  min-height: calc(100% - 36px);
  width: calc(100% - 36px);
}

.container--contents-centered {
  justify-content: center;
  align-items: center;
}

.container--no-padding {
  padding: 0;
}

Page Layout:

scss
.page {
  --topbar-height: 80px;
  max-width: 1216px;
  margin: 0 auto;
  padding: 48px calculated-sides;

  // Responsive padding and width management
  // Automatically adjusts for mobile, tablet, and desktop
}

.page--contents-max-width {
  > * {
    max-width: 780px;
  }
}

.page--no-extra-padding {
  --width-sections: calc(100% - 32px);
  --padding-sections-left: 32px;
}

Border Radius Scale:

Variable
Value
Use Case
$border-radius
4px (0.25rem)
Default, small elements
$border-radius--1
8px (0.5rem)
Buttons, inputs
$border-radius--1-5
12px (0.75rem)
Medium cards
$border-radius--2
16px (1rem)
Cards, modals
$border-radius--3
24px (1.5rem)
Large containers
$border-radius--4
32px (2rem)
Hero sections

Responsive Breakpoints:

Breakpoint
Max Width
Device
Mobile S
320px
Small mobile devices
Mobile
375px
Standard mobile devices
Mobile Landscape
568px
Mobile in landscape orientation
iPad S
768px
Small tablets
Mobile L Landscape
812px
Large mobile in landscape
iPad
834px
Standard tablets

The dimensions module automatically applies responsive padding adjustments at each breakpoint. The .page class uses CSS custom properties to maintain consistent spacing across different screen sizes.

scss
@use '@san-siva/stylekit/styles/dimensions.module.scss' as dims;

.card {
  border-radius: dims.$border-radius--2;
  max-width: dims.$max-width--page-contents;
}

.rounded-button {
  border-radius: dims.$border-radius--1;
}

// Use built-in container
.my-container {
  @extend .container;
  @extend .container--contents-centered;
}

Best Practices

Follow these guidelines to get the most out of StyleKit:

Module Organization

Use namespaces to avoid conflicts:

scss
// Good: Use namespaces with @use
@use '@san-siva/stylekit/styles/colors.module.scss' as colors;
@use '@san-siva/stylekit/styles/utils.module.scss' as utils;

.component {
  color: colors.$color--primary;
  padding: utils.space(2);
}

// Avoid: @import mixes everything into global scope
@import '@san-siva/stylekit/styles/colors.module.scss';  // Don't do this

Spacing Consistency

Always use the spacing scale:

scss
// Good: Use spacing scale
.section {
  margin-bottom: utils.space(4);  // 32px from scale
  padding: utils.space(3);         // 24px from scale
}

// Avoid: Arbitrary values break consistency
.section {
  margin-bottom: 35px;  // Don't do this
  padding: 22px;        // Don't do this
}

Color Usage

Use semantic color names:

scss
// Good: Semantic naming makes intent clear
.error-message {
  color: colors.$color--error;
  background: colors.$color--error-light;
}

.primary-button {
  background: colors.$color--primary;
  color: colors.$color--base;
}

// Avoid: Direct hex values lose semantic meaning
.error-message {
  color: #ff4232;  // What does this color represent?
}

Typography Scales

Stick to the type scale:

scss
// Good: Use predefined sizes
h1 {
  font-size: type.$font-size--h1;  // 36px
}

.small-text {
  font-size: type.$font-size--small;  // 12px
}

// Avoid: Random font sizes
h1 {
  font-size: 37px;  // Why not 36px from the scale?
}

Utility Class Composition

Combine utility classes effectively:

tsx
// Good: Compose utilities for rapid development
<div className={`
  ${styles['margin-bottom--4']}
  ${styles['padding-top--3']}
  ${styles['font-size--h2']}
`}>
  Content
</div>

// Also good: Use SCSS variables for complex components
.complex-component {
  margin-bottom: utils.space(4);
  padding-top: utils.space(3);
  font-size: type.$font-size--h2;
  color: colors.$color--primary;
}

Framework Integration

React / Next.js

tsx
// Import SCSS module
import styles from '@san-siva/stylekit/styles/index.module.scss';

export function Card({ children }) {
  return (
    <div className={styles['padding-top--4']}>
      <h2 className={`${styles['font-size--h2']} ${styles['margin-bottom--2']}`}>
        Card Title
      </h2>
      <div className={styles['margin-top--3']}>
        {children}
      </div>
    </div>
  );
}

Vue.js

vue
<template>
  <div :class="$style['padding-top--4']">
    <h2 :class="[$style['font-size--h2'], $style['margin-bottom--2']]">
      Card Title
    </h2>
  </div>
</template>

<style module>
@use '@san-siva/stylekit/styles/index.module.scss' as *;
</style>

Angular

scss
// component.scss
@use '@san-siva/stylekit/styles/colors.module.scss' as colors;
@use '@san-siva/stylekit/styles/utils.module.scss' as utils;

:host {
  display: block;
  padding: utils.space(4);
}

.card {
  background: colors.$color--base;
  border: 1px solid colors.$color--border;
}

Customization

While StyleKit provides sensible defaults, you can customize it for your needs:

Extending the Color Palette

scss
// your-colors.scss
@use '@san-siva/stylekit/styles/colors.module.scss' as stylekit-colors;

// Add your custom colors
$color--brand: #your-color;
$color--custom: #another-color;

// Use both StyleKit and custom colors
.my-component {
  background: stylekit-colors.$color--primary;
  border-color: $color--brand;
}

Custom Spacing Values

scss
@use '@san-siva/stylekit/styles/utils.module.scss' as utils;

// Define custom spacing
$spacing-custom: utils.rem(72);

.special-section {
  margin-bottom: $spacing-custom;
  // Or use the built-in space function
  padding: utils.space(5);  // 40px
}

Typography Override

scss
@use '@san-siva/stylekit/styles/typography.module.scss' as type;

// Override with your font
$custom-font-family: 'Your Font', sans-serif;

.heading {
  font-family: $custom-font-family;
  // But still use StyleKit's scale
  font-size: type.$font-size--h1;
  font-weight: type.$font-weight--700;
}

Performance Considerations

Import only what you need: StyleKit's modular architecture allows you to import specific modules rather than the entire library, reducing your bundle size.

scss
// Smaller bundle: Import specific modules
@use '@san-siva/stylekit/styles/colors.module.scss' as colors;
@use '@san-siva/stylekit/styles/utils.module.scss' as utils;

// vs.

// Larger bundle: Import everything
@use '@san-siva/stylekit/styles/index.module.scss' as stylekit;

Utility classes vs. SCSS variables:

  • Use utility classes for rapid prototyping and simple layouts
  • Use SCSS variables and functions for complex components with multiple computed styles
  • Utility classes are included in the CSS bundle only when used (with proper tree-shaking)

Migration Guide

If you're migrating from a custom design system or another framework:

  1. Audit your current styles: Identify colors, spacing, and typography patterns in your existing codebase
  2. Map to StyleKit tokens: Find equivalent values in StyleKit's design tokens
  3. Incremental adoption: Start with new components, gradually refactor existing ones
  4. Create custom tokens: For values not in StyleKit, create your own tokens using StyleKit's patterns
  5. Test thoroughly: Visual regression testing helps catch unintended changes

Contributing

Contributions are welcome! Please fork the repository and submit pull requests. For bugs or feature requests, open an issue on the repository.

View source code, report issues, and contribute

License

This project is licensed under the MIT License.

About

Author: Santhosh Siva
GitHub: https://github.com/san-siva