Theme System Documentation

Architecture Overview

The styling is split into base structure (layout) and themes (visual styling):

Base Files (Structure Only)

• vanilla-grid.css - Grid component layout, injected by <vn-grid> itself
• styles.css - App structure (grids, spacing, layout)

Theme Files (Visual Styling)

• themes/app-{name}.css (this folder) - App colors, fonts, shadows, UI chrome
• vn-grid-{name}.css - Grid colors, fonts, shadows, borders. Shipped by the component in src/vanilla-grid/themes/ and loaded by <vn-grid> from its theme attribute — this app ships no grid CSS of its own

Available Themes

1. Default Theme (Purple Gradient)

Classic purple gradient design with vibrant colors:

• Colors: Purple gradients (#667eea, #764ba2)
• Style: Modern, vibrant, gradients
• Files:
  • themes/app-default.css

2. Google Material Theme

Inspired by Google Material Design:

• Colors: Google Blue (#1a73e8), clean neutral surfaces
• Style: Modern, clean, subtle elevation
• Typography: Roboto
• Files:
  • themes/app-material.css

3. SAP Fiori Theme

Based on SAP Fiori Design System:

• Colors: Fiori Blue (#0a6ed1), neutral grays
• Style: Clean, professional, enterprise
• Typography: '72' font family (SAP's typeface)
• Features:
  • Alternating row backgrounds
  • Minimal borders
  • Subtle shadows
  • High information density
• Files:
  • themes/app-fiori.css

4. IBM Carbon Theme

Based on IBM Carbon Design System:

• Colors: IBM Blue (#0f62fe), dark text (#161616)
• Style: Sharp, industrial, minimal
• Typography: 'IBM Plex Sans' font family
• Features:
  • Dark headers (#161616)
  • No rounded corners (sharp edges)
  • No row striping (hover only)
  • Elevation shadows
  • High contrast
• Files:
  • themes/app-carbon.css

5. IBM Carbon Dark Theme

Based on IBM Carbon Design System (Dark Mode):

• Colors: IBM Blue 50 (#78a9ff), Gray 100 background (#161616)
• Style: Dark mode, high contrast, minimal
• Typography: 'IBM Plex Sans' font family
• Features:
  • Dark backgrounds (#161616, #262626)
  • Light text (#f4f4f4, #c6c6c6)
  • No rounded corners (sharp edges)
  • Dark row striping (hover only)
  • Subtle shadows
  • WCAG AA compliant contrast
• Files:
  • themes/app-carbon-dark.css

6. Glow UI Theme (Light)

Inspired by Glow UI:

• Colors: Indigo (#6366f1), neutral grays, soft elevation
• Style: Modern, soft 12px corners, subtle shadows
• Typography: 'Inter' font family
• Files:
  • themes/app-glow.css

7. Glow UI Dark Theme

Inspired by Glow UI (Dark Mode):

• Colors: Indigo 400 (#818cf8), neutral 900/950 surfaces (#0a0a0a / #171717)
• Style: Dark mode, soft 12px corners
• Typography: 'Inter' font family
• Files:
  • themes/app-glow-dark.css

8. Microsoft Fluent 2 Theme

Based on Microsoft Fluent 2:

• Colors: Communication blue (#0f6cbd), neutral surfaces
• Style: Compact 4px corners, Fluent depth shadows
• Typography: 'Segoe UI Variable' font family
• Files:
  • themes/app-fluent.css

How to Switch Themes

Via the <vn-grid> Web Component

Grid themes are now managed by the <vn-grid> element. Set the theme attribute declaratively or switch at runtime:

<vn-grid id="peopleGrid" theme="material">
    ...
</vn-grid>

// Switch at runtime
document.getElementById('peopleGrid').setTheme('carbon-dark');

The app-level theme CSS is still loaded via a <link> tag in index.html:

<link id="appThemeLink" rel="stylesheet" href="themes/app-default.css">

Dynamic Theme Switching (JavaScript)

switchTheme(themeName) in modules/theme.js swaps the app theme <link href> to themes/app-<name>.css and calls setTheme(name) + refresh() on every <vn-grid> on the page, so one name drives both layers.

Creating New Themes

Step 1: Copy Template

Copy the app-theme template as a starting point:

cp themes/TEMPLATE-app-theme.css themes/app-mytheme.css

The grid needs a theme under the same name: either one of the eight built-ins, or a custom one started from src/vanilla-grid/themes/TEMPLATE-vn-grid-theme.css and registered with VanillaGridElement.registerTheme('mytheme', '<path>').

Step 2: Customize Colors

Edit your new theme files, focusing on:

• Primary colors (headers, buttons, highlights)
• Background colors (body, containers, rows)
• Border colors and styles
• Text colors and font families
• Shadow effects

Step 3: Test Theme

Add an <option value="mytheme"> to the #themeSelector dropdown in index.html and pick it — switchTheme() loads both layers.

Design System Guidelines

SAP Fiori

• Primary: #0a6ed1 (Fiori Blue)
• Neutrals: #32363a (text), #6a6d70 (muted), #fafafa (backgrounds)
• Borders: 1px solid, minimal
• Shadows: Subtle, rare
• Border Radius: 0-0.25rem (mostly square)
• Typography: '72', Helvetica Neue
• Row Striping: Yes (alternating backgrounds)

IBM Carbon

• Primary: #0f62fe (IBM Blue)
• Neutrals: #161616 (text), #525252 (muted), #f4f4f4 (backgrounds)
• Borders: 1px solid #e0e0e0
• Shadows: Box shadows for elevation (0 2px 6px rgba(0,0,0,0.2))
• Border Radius: 0 (sharp corners)
• Typography: IBM Plex Sans
• Row Striping: No (hover only)
• Header: Dark (#161616) with light text

IBM Carbon Dark

• Primary: #78a9ff (IBM Blue 50 - adjusted for dark mode)
• Neutrals: #f4f4f4 (text), #c6c6c6 (secondary), #161616 (background)
• Surface: #262626 (Gray 90), #393939 (Gray 80)
• Borders: 1px solid #393939 (Gray 80)
• Shadows: Box shadows for elevation (0 2px 6px rgba(0,0,0,0.8))
• Border Radius: 0 (sharp corners)
• Typography: IBM Plex Sans
• Row Striping: No (hover only)
• Header: Dark gray (#262626) with light text
• Hover: #262626 (Gray 90) for body rows

Material Design

• Primary: #1976d2 (Material Blue)
• Neutrals: rgba(0,0,0,0.87) (text), #fafafa (backgrounds)
• Borders: Minimal, use shadows instead
• Shadows: Elevation system (0-24dp)
• Border Radius: 4px
• Typography: Roboto
• Row Striping: No (hover + selection states)

Theme Validation Checklist

When creating a new theme, ensure you style:

Grid Components

Grid styling is owned by the component's theme file, not this app — see the required token set in src/vanilla-grid/themes/TEMPLATE-vn-grid-theme.css.

App Components

• body - Background, font family
• .container - Background, shadow, border
• .tabs - Background, borders
• .tab-button - Colors, borders, radius
• .tab-button.active - Active state styling
• header - Background, text color
• Form controls - Borders, backgrounds, focus states
• Buttons - Colors, hover, active states
• .status - Info, success, error states
• footer - Background, text color

Best Practices

1. Keep base files unchanged - Only edit theme files
2. Use consistent spacing - Match design system grid (4px, 8px, etc.)
3. Test accessibility - Ensure contrast ratios meet WCAG AA standards
4. Mobile responsive - Test on small screens
5. Browser compatibility - Test gradients, shadows, fonts
6. Performance - Avoid heavy box-shadows on many elements

Troubleshooting

Theme not applying

• Check file paths in <link> tags
• Verify CSS files exist in themes/ folder
• Check browser console for 404 errors
• Clear browser cache

Partial styling

• Ensure the app theme name matches a grid theme the <vn-grid> can resolve
• Check CSS specificity (theme styles should override base)
• Verify no !important rules in base files

Conflicting styles

• Load base files before theme files
• Keep only one theme active at a time
• Use browser DevTools to inspect applied styles