Documentation

Style Guide

* A style guide primarily focuses on visual design and branding. It defines the rules and standards for using visual elements consistently across a product or brand.

* The style guide is often more static and focuses on the aesthetics of design, such as color schemes, typography, iconography, and brand guidelines.

* It is usually document-focused and can be used as a reference for designers to ensure they follow the brand's established visual identity.

Design System

A design system is a comprehensive framework that includes rules, guidelines, UI components, patterns, and assets (like color palettes, typography, and icons) that guide the development of consistent user interfaces. A design system helps maintain visual coherence and usability across different platforms and products.
* Example:
Your design system will include:
* Color palette (primary, secondary, semantic colors, and shades).

* Typography rules (font family, sizes, weights, etc.).

* Component library (buttons, forms, inputs, modals, etc.).

* Spacing, layout, and grid systems.

* Brand guidelines to ensure consistency across products.

🔹 Key Differences

Aspect	Style Guide	Design System
Purpose	Visual consistency and branding	Complete system for design and development
Focus	Visual identity (colors, typography, logos)	UI components, code implementation, interaction
Content	Colors, fonts, imagery, icons, branding	Components, design patterns, tokens, accessibility
Scope	Limited to aesthetics and branding	Comprehensive, covering design and development
Audience	Designers, marketers	Designers, developers, product teams
Evolution	Static, updated occasionally	Dynamic, continuously evolving
Components	Basic UI elements, brand usage rules	Reusable UI components, patterns, tokens, code

---

Color Palette

Color palettes are created by adjusting the lightness and saturation of the base color.
Each shade has a different intensity:

✅ Primary Base Color → The main color that represents your brand.
→ Should be the strongest and most recognizable color. It’s used for the logo, buttons, headers, and important elements.

✅ Secondary Base Color → A supporting color that complements the primary.
→ Should complement the primary but offer contrast. It’s used for backgrounds, highlights, and soft UI elements.

✅ Tertiary Base Color → Complement the primary + secondary colors,
→Enhance contrast and make important elements pop
→Be used sparingly for highlights, CTA buttons, or small UI details

🔹How Do Color Shades Work?

Shade	Color Description
100	Very Light (Backgrounds, soft UI)
200	Light (Secondary backgrounds)
300	Soft (Hover effects, highlights)
400	Medium (Icons, subtle highlights)
500	Base (Main buttons, logo, brand identity)
600	Darker (Strong buttons, contrast text)
700	Very Dark (Borders, bold elements)
800	Deep (Headings, dark UI)
900	Deepest / Darkest (Strongest contrast)

🔹 Brand Color

Role	Color Name	HEX Code	Usage
Primary Color	Blue 500	#3B82F6	Main branding (logo, buttons, headings)
Secondary Color	Purple 500	#A855F7	UI highlights, backgrounds
Tertiary Color Accent	Orange 500	#F97316	CTA buttons, special highlights

🔹 System Color

System Color	Generated from?	Value
Success	Green Accent	#22C55E
Warning	Orange Accent	#F97316
Danger	Red Accent	#EF4444
Info	Lighter Blue	#60A5FA
Background Light	Very Light Primary - lighten($primary, 20%)	#EFF6FF
Background Dark	Very Dark Primary - darken($primary, 20%)	#1E3A8A
$secondary	A lighter shade of primary	mix($primary, #fff, 50%)
$tertiary	A deeper tone of primary	mix($primary, #000, 30%)

🔹 System ColorUnderstanding Hue (Color Wheel Degrees)

Every color in HSL is represented as a degree (0°–360°) on the color wheel:

• 0° → Red
• 60° → Yellow
• 120° → Green
• 180° → Cyan
• 240° → Blue
• 300° → Purple

🔹 Light Mode → Dark Mode Mapping

Light Mode (50-950)	Dark Mode (50-950)
primary-50 (lightest)	primary-950 (darkest)
primary-100	primary-900
primary-200	primary-800
primary-300	primary-700
primary-400	primary-600
primary-500 (default)	primary-500 (default)
primary-600	primary-400
primary-700	primary-300
primary-800	primary-200
primary-900 (darkest)	primary-100
primary-950 (extra dark)	primary-50 (lightest)

---

Naming Convention Guide for Colors

(Primitive, Variables, and JSON Tokens).

1. Primitive Colors (Foundation Colors)

💡 Definition:
These are the raw, static color values. They serve as the foundation for your entire color system.

💡 Naming Rule:
Use semantic names + shade values (e.g., 50-950 scale).
* Format: $colorName-shade
* Example: $blue-50, $purple-500, $gray-900
*

2. CSS Variables (For Theming)

💡 Definition:
These are dynamic variables based on Primitive Colors. They allow easy theme switching (light/dark modes).

💡 Naming Rule:
Use CSS variable format with --color-category-level.
* Format: --color-{role}-{shade}
* Example: --color-primary-500, --color-text-muted
*

3. JSON Design Tokens (For API & Exports)

💡 Definition:
JSON format is used to store design tokens. It can be imported into SCSS, JS, or CSS.

💡 Naming Rule:
Use structured JSON hierarchy
* Format: { "colors": { "category": { "shade": "hex" } } }
* Example: "colors.primary.500": "#3B82F6"
*

4. Semantic Naming (Function-Based Colors in Design Systems)

💡 Definition:
Semantic naming is a method of defining colors based on their intended role or function in the design system, rather than their specific hue. Instead of naming colors based on their shade ($blue-500), they are assigned meaningful names ($primary, $secondary, $success). This improves readability, maintainability, and scalability, making it easier to manage themes and UI consistency.

💡 Naming Rule:
Use functional names instead of specific color names.
* Format: $role: $color;
* Example: $primary: $blue-500;

🔹 Final Naming Summary

Format	Naming Convention	Example
Primitive (SCSS)	$colorName-shade	$blue-500, $orange-50
CSS Variables	--color-category-shade	--color-primary-500, --color-text-muted
JSON Tokens	{ "colors": { "category": { "shade": "hex" } } }	"colors.primary.500": "#3B82F6"
Semantic (SCSS)	$role or $role-state	$primary: $blue-500;, $success: $green-500;
Surface (SCSS)	$surface-layer-state	$surface-bg: $gray-50;, $surface-bg-dark: $gray-900;
System Colors (SCSS)	$status-bg	$success-bg: $green-100;, $danger-bg: $red-100;
Text Colors (SCSS)	$text-role	$text-primary: $gray-900;, $text-on-dark: $gray-100;

🔹 Design Token Naming Conventions Table

#	Naming Type	Definition	Naming Rule	Example
1	Primitive Colors (Raw Color Palette)	Direct color values without assigned meaning. Used as a base for theme colors.	Use hue-based names with numeric scales (e.g., 50-950).	$blue-50: #EBF8FF; $blue-500: #3B82F6;
2	SCSS Variables (For Global Usage)	Variables used within SCSS to define reusable colors. These can be imported across stylesheets.	Use kebab-case or camelCase for naming.	@theme { --color-brand-50: #e8eaee; }
3	JSON Design Tokens (For API & Exports)	JSON format is used to store design tokens. It can be imported into SCSS, JS, or CSS.	Use structured JSON hierarchy.	{ "colors": { "brand": { "50": "#EBF3FE" } } }
4	Semantic Naming (Function-Based Colors in Design Systems)	Colors are assigned based on their role in the design, rather than hue. Used for UI components and maintainable theming.	Use functional names instead of specific color names.	$primary: $blue-500; $success: $green-500; $text-primary: $gray-900;
5	Surface Colors (For UI Layers & Backgrounds)	Defines background layers with subtle variations, useful for light/dark themes.	Use context-based names for UI surfaces.	$surface-bg: $gray-50; $surface-bg-dark: $gray-900;
6	System Colors (For Status & Alerts)	Assigns colors for success, warnings, errors, and information messages in UI alerts.	Use meaningful names for status indicators.	$success-bg: $green-100; $danger-bg: $red-100;
7	Text Colors (For Readability & Contrast)	Defines text colors to ensure contrast across different UI elements.	Use names like text-primary, text-secondary, text-muted.	$text-primary: $gray-900; $text-on-dark: $gray-100;

Primary - Blue Color Palette

{
  "colors": {
    "brand": {
      50: "#EBF3FE",
      100: "#D8E6FD",
      200: "#B1CEFB",
      300: "#8AB5FA",
      400: "#639CF8",
      500: "#3B82F6",
      600: "#0B60EA",
      700: "#0848B0",
      800: "#053075",
      900: "#03183B",
      950: "#010C1D"
    }
  }
}
    

Secondary - Purple Color Palette

{
  "colors": {
    "brand": {
      50: "#F8F0FE",
      100: "#EEDDFD",
      200: "#DCBBFC",
      300: "#CB99FA",
      400: "#BA77F9",
      500: "#A855F7",
      600: "#8815F4",
      700: "#6609BE",
      800: "#44067F",
      900: "#22033F",
      950: "#120222"
    }
  }
}
    

Tertiary - Orange Color Palette

{
  "colors": {
    "brand": {
      50: "#FEF0E6",
      100: "#FEE4D2",
      200: "#FDC7A1",
      300: "#FBAC74",
      400: "#FA8F42",
      500: "#F97316",
      600: "#D15A05",
      700: "#9F4504",
      800: "#682D03",
      900: "#371801",
      950: "#190B01"
    }
  }
}
    

Grayscale / 10% Blended of Base Color with Dark Gray

{
  "colors": {
    "brand": {
      50: "#E8EAEE",
      100: "#D3D7DE",
      200: "#A7B0BE",
      300: "#78869B",
      400: "#556072",
      500: "#343B46",
      600: "#292F38",
      700: "#1E2229",
      800: "#16191D",
      900: "#0B0C0F",
      950: "#040506"
    }
  }
}
    

System - Green Color Scheme

{
  "colors": {
    "brand": {
      50: "#E1F9EE",
      100: "#C3F4DD",
      200: "#8BEABD",
      300: "#4FDE9B",
      400: "#24C278",
      500: "#198754",
      600: "#146C43",
      700: "#0F5233",
      800: "#0A3823",
      900: "#051A10",
      950: "#020D08"
    }
  }
}
    

System - Cyan Color Scheme

{
  "colors": {
    "brand": {
      50: "#E7FAFE",
      100: "#CFF5FC",
      200: "#9EEAFA",
      300: "#6EE0F7",
      400: "#3ED6F4",
      500: "#0DCAF0",
      600: "#0BA3C1",
      700: "#087A91",
      800: "#055161",
      900: "#032930",
      950: "#011418"
    }
  }
}
    

System - Yellow Color Scheme

{
  "colors": {
    "brand": {
      50: "#FFF9E5",
      100: "#FFF2CC",
      200: "#FFE79E",
      300: "#FFDA6B",
      400: "#FFCD38",
      500: "#FFC107",
      600: "#D19D00",
      700: "#9E7700",
      800: "#6B5000",
      900: "#332600",
      950: "#191300"
    }
  }
}
    

System - Red Color Scheme

{
  "colors": {
    "brand": {
      50: "#FBE9EB",
      100: "#F8D8DB",
      200: "#F1ACB3",
      300: "#EA858F",
      400: "#E35E6B",
      500: "#DC3545",
      600: "#BB2030",
      700: "#8B1824",
      800: "#5B1017",
      900: "#30080C",
      950: "#160406"
    }
  }
}