+
+
+
+
diff --git a/src/stories/foundations/Colors.mdx b/src/stories/foundations/Colors.mdx
new file mode 100644
index 00000000..584c1ede
--- /dev/null
+++ b/src/stories/foundations/Colors.mdx
@@ -0,0 +1,238 @@
+import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks';
+
+
+
+# Colors
+
+The Hensei color system is built around a neutral grey scale, accent colors, and element-specific palettes for the six Granblue Fantasy elements.
+
+## Grey Scale
+
+The foundation of our color system. Used for backgrounds, text, borders, and UI elements.
+
+
+
+
+
+
+
+
+
+## Accent Colors
+
+Primary accent colors for interactive elements and highlights.
+
+
+
+
+
+
+
+## Element Colors
+
+Granblue Fantasy element-specific colors used for theming characters, weapons, and summons.
+
+### Wind
+
+
+
+
+
+### Fire
+
+
+
+
+
+### Water
+
+
+
+
+
+### Earth
+
+
+
+
+
+### Light
+
+
+
+
+
+### Dark
+
+
+
+
+
+## Special Purpose Colors
+
+### Extra Weapons (Purple)
+
+
+
+
+
+### Subaura Summons (Orange)
+
+
+
+
+
+### Game Tokens
+
+
+
+
+
+
+
+## CSS Custom Properties
+
+All colors are available as CSS custom properties through the theme system. They automatically switch between light and dark mode values.
+
+```css
+/* Usage in components */
+.my-component {
+ background: var(--card-bg);
+ color: var(--text-primary);
+ border: 1px solid var(--border-subtle);
+}
+
+/* Element-specific theming */
+.wind-themed {
+ background: var(--wind-bg);
+ color: var(--wind-text);
+}
+```
+
+### Common Variables
+
+| Variable | Description |
+|----------|-------------|
+| `--background` | Page background |
+| `--card-bg` | Card/panel background |
+| `--text-primary` | Primary text color |
+| `--text-secondary` | Secondary/muted text |
+| `--border-subtle` | Subtle borders |
+| `--accent-blue` | Primary accent |
+| `--accent-yellow` | Highlight/selection |
diff --git a/src/stories/foundations/Elements.mdx b/src/stories/foundations/Elements.mdx
new file mode 100644
index 00000000..015d4d6b
--- /dev/null
+++ b/src/stories/foundations/Elements.mdx
@@ -0,0 +1,232 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+
+
+# Elements
+
+Granblue Fantasy features six elemental types that form a core part of the game's mechanics. Each element has a distinct color palette used throughout Hensei for theming characters, weapons, summons, and UI components.
+
+## Element Wheel
+
+The six elements form a weakness/advantage cycle:
+
+
+
+
+
Wind
+
+
+
Fire
+
+
+
Water
+
+
+
Earth
+
+
+
Light
+
+
+
Dark
+
+
+
+
+**Advantage cycle:**
+- Wind → Earth → Water → Fire → Wind
+- Light ↔ Dark (mutual advantage)
+
+## Element Color Palettes
+
+Each element has multiple color values for different contexts:
+
+### Wind (Green)
+
+
+
+ Text Light
+
+
+ Text Dark
+
+
+ Background
+
+
+ Portrait
+
+
+
+### Fire (Red)
+
+
+
+ Text Light
+
+
+ Text Dark
+
+
+ Background
+
+
+ Portrait
+
+
+
+### Water (Blue)
+
+
+
+ Text Light
+
+
+ Text Dark
+
+
+ Background
+
+
+ Portrait
+
+
+
+### Earth (Orange)
+
+
+
+ Text Light
+
+
+ Text Dark
+
+
+ Background
+
+
+ Portrait
+
+
+
+### Light (Yellow)
+
+
+
+ Text Light
+
+
+ Text Dark
+
+
+ Background
+
+
+ Portrait
+
+
+
+### Dark (Purple)
+
+
+
+ Text Light
+
+
+ Text Dark
+
+
+ Background
+
+
+ Portrait
+
+
+
+## CSS Custom Properties
+
+Element colors are available as CSS variables that adapt to light/dark themes:
+
+```css
+/* Each element provides these variables */
+--{element}-bg /* Main background color */
+--{element}-bg-hover /* Hover state background */
+--{element}-text /* Primary text color */
+--{element}-text-hover /* Hover state text */
+--{element}-portrait-bg /* Portrait/card background */
+--{element}-shadow /* Box shadow color */
+--{element}-accent /* Accent color */
+```
+
+### Example Usage
+
+```css
+.wind-card {
+ background: var(--wind-bg);
+ color: var(--wind-text);
+ box-shadow: 0 2px 8px var(--wind-shadow);
+}
+
+.wind-card:hover {
+ background: var(--wind-bg-hover);
+ color: var(--wind-text-hover);
+}
+```
+
+## Element Buttons
+
+Each element has a dedicated button color:
+
+
+
+
+
+
+
+
+
+
+## Navigation Selected States
+
+Elements have specific colors for selected navigation items:
+
+| Element | Background | Text |
+|---------|------------|------|
+| Wind | `#cdffed` | `#006a45` |
+| Fire | `#ffcdcd` | `#6e0000` |
+| Water | `#cdedff` | `#00639c` |
+| Earth | `#ffe2cd` | `#863504` |
+| Light | `#fffacd` | `#715100` |
+| Dark | `#f2cdff` | `#560075` |
+
+## Focus Ring Mixins
+
+SCSS mixins for element-specific focus rings:
+
+```scss
+@use 'themes/colors';
+
+.wind-input:focus {
+ @include colors.focus-ring-wind();
+}
+
+.fire-input:focus {
+ @include colors.focus-ring-fire();
+}
+```
+
+Each mixin applies:
+- Appropriate border color
+- Matching box shadow with transparency
+- Removes default outline
+
+## Components with Element Support
+
+The following components support element theming:
+
+- **Button** - `element` prop for colored buttons
+- **SegmentedControl** - `element` prop for colored segments
+- **ElementLabel** - Displays element icon with color
+- **CharacterUnit** - Border color based on character element
+- **WeaponUnit** - Border color based on weapon element
+- **SummonUnit** - Border color based on summon element
diff --git a/src/stories/foundations/Spacing.mdx b/src/stories/foundations/Spacing.mdx
new file mode 100644
index 00000000..e23d9438
--- /dev/null
+++ b/src/stories/foundations/Spacing.mdx
@@ -0,0 +1,143 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+
+
+# Spacing
+
+Hensei uses an 8px base unit spacing system for consistent rhythm throughout the interface.
+
+## Base Unit
+
+```scss
+$unit: 8px;
+```
+
+All spacing values are multiples of this base unit, creating visual harmony and predictable layouts.
+
+## Spacing Scale
+
+
+
+
$unit-fourth
+
+ 2px - Micro spacing
+
+
+
$unit-half
+
+ 4px - Tight spacing
+
+
+
$unit
+
+ 8px - Base unit
+
+
+
$unit-2x
+
+ 16px - Default gap
+
+
+
$unit-3x
+
+ 24px - Medium spacing
+
+
+
$unit-4x
+
+ 32px - Section spacing
+
+
+
$unit-6x
+
+ 48px - Large spacing
+
+
+
$unit-8x
+
+ 64px - XL spacing
+
+
+
+## Full Scale Reference
+
+| Token | Value | Pixels | Usage |
+|-------|-------|--------|-------|
+| `$unit-fourth` | $unit / 4 | 2px | Borders, micro adjustments |
+| `$unit-half` | $unit / 2 | 4px | Tight gaps, small padding |
+| `$unit-three-quarter` | $unit * 0.75 | 6px | Small gaps |
+| `$unit` | 8px | 8px | Base unit |
+| `$unit-2x` | $unit * 2 | 16px | Standard gap/padding |
+| `$unit-3x` | $unit * 3 | 24px | Medium spacing |
+| `$unit-4x` | $unit * 4 | 32px | Section spacing |
+| `$unit-5x` | $unit * 5 | 40px | Large gaps |
+| `$unit-6x` | $unit * 6 | 48px | XL gaps |
+| `$unit-8x` | $unit * 8 | 64px | Page margins |
+| `$unit-10x` | $unit * 10 | 80px | Hero spacing |
+| `$unit-12x` | $unit * 12 | 96px | Section dividers |
+
+## CSS Custom Properties
+
+Semantic spacing aliases are available as CSS variables:
+
+```css
+:root {
+ --spacing-xs: 8px; /* $unit */
+ --spacing-sm: 16px; /* $unit-2x */
+ --spacing-md: 32px; /* $unit-4x */
+ --spacing-lg: 64px; /* $unit-8x */
+ --spacing-xl: 96px; /* $unit-12x */
+}
+```
+
+## Breakpoints
+
+Responsive breakpoints for different device sizes:
+
+| Token | Value | Device |
+|-------|-------|--------|
+| `$phone` | 375px | Mobile phones |
+| `$tablet` | 768px | Tablets |
+| `$laptop` | 1280px | Laptops |
+| `$desktop` | 1920px | Desktop monitors |
+
+### Grid Width
+
+The standard grid/content width:
+
+```scss
+$grid-width: 780px;
+```
+
+## Component Heights
+
+Standard heights for grid representation components:
+
+| Token | Value | Component |
+|-------|-------|-----------|
+| `$character-rep-height` | 111px | Character unit/rep |
+| `$weapon-rep-height` | 109.75px | Weapon unit/rep |
+| `$summon-rep-height` | 117px | Summon unit/rep |
+
+## Usage in SCSS
+
+```scss
+@use 'themes/spacing' as spacing;
+
+.card {
+ padding: spacing.$unit-2x;
+ margin-bottom: spacing.$unit-3x;
+ gap: spacing.$unit;
+}
+
+.hero-section {
+ padding: spacing.$unit-8x 0;
+ margin-bottom: spacing.$unit-6x;
+}
+
+@media (max-width: spacing.$tablet) {
+ .card {
+ padding: spacing.$unit;
+ }
+}
+```
diff --git a/src/stories/foundations/Typography.mdx b/src/stories/foundations/Typography.mdx
new file mode 100644
index 00000000..2dbf1aa2
--- /dev/null
+++ b/src/stories/foundations/Typography.mdx
@@ -0,0 +1,119 @@
+import { Meta, Typeset } from '@storybook/addon-docs/blocks';
+
+
+
+# Typography
+
+Hensei uses the **Goalking** variable font as its primary typeface, with system fonts as fallbacks.
+
+## Font Family
+
+```css
+--font-family: 'Goalking', system-ui, sans-serif;
+```
+
+The Goalking font is a variable font supporting weights from 100-900, loaded from `/fonts/gk-variable.woff2`.
+
+## Font Weights
+
+| Weight | Value | Usage |
+|--------|-------|-------|
+| Normal | 400 | Body text, descriptions |
+| Medium | 500 | Labels, emphasized text |
+| Bold | 600 | Headings, important text |
+
+## Font Sizes
+
+Our font sizes use `rem` units based on a 10px base (62.5% of 16px), making calculations simple: 1rem = 10px.
+
+
+
+### Size Scale
+
+| Token | Size | Pixels | Usage |
+|-------|------|--------|-------|
+| `$font-tiny` | 1.1rem | 11px | Badges, captions |
+| `$font-small` | 1.3rem | 13px | Secondary text, metadata |
+| `$font-button` | 1.5rem | 15px | Button text |
+| `$font-name` | 1.5rem | 15px | Character/item names |
+| `$font-regular` | 1.6rem | 16px | Body text |
+| `$font-medium` | 1.8rem | 18px | Subheadings |
+| `$font-large` | 2.1rem | 21px | Section headers |
+| `$font-xlarge` | 2.4rem | 24px | Page titles |
+| `$font-xxlarge` | 2.8rem | 28px | Hero text |
+
+## Font Weight Examples
+
+
+
Normal (400): The quick brown fox jumps over the lazy dog
+
Medium (500): The quick brown fox jumps over the lazy dog
+
Bold (600): The quick brown fox jumps over the lazy dog