[Theme] Enhance customization capabilities

[ravisuhag]

Summary

Enhance the ThemeProvider to support comprehensive theming customization, making Apsara more adaptable to different design requirements and use cases.

Current Capabilities

The ThemeProvider already handles:

• Theme mode (light / dark / system)
• Style variants (modern / traditional)
• Accent colors (indigo / orange / mint)
• Gray scales (gray / mauve / slate / sage)
• Persistence via localStorage
• System preference detection
• FOUC prevention with inline script

Proposed Enhancements

1. Scaling/Density

scaling: 'compact' | 'default' | 'comfortable' | 'spacious'

Adjusts spacing tokens globally for different UI densities. Useful for data-dense applications vs content-focused interfaces.

2. Border Radius Control

radius: 'none' | 'small' | 'medium' | 'large' | 'full'

Global control over component roundness beyond style variants. Allows sharp corners for enterprise apps or pill-shaped components for playful designs.

3. Typography Scale

fontFamily: { body: string; heading: string; mono: string }
fontSize: 'small' | 'default' | 'large'  // Base scale multiplier

Allow consumers to customize font families and adjust the base font size scale.

4. Custom Token Overrides

tokens: {
  colors?: Partial<ColorTokens>
  spacing?: Partial<SpacingTokens>
  radius?: Partial<RadiusTokens>
  shadows?: Partial<ShadowTokens>
}

Allow consumers to override any design token for brand-specific customization.

5. Component-Level Defaults

components: {
  Button?: { variant?: 'solid' | 'outline'; size?: 'sm' | 'md' }
  Input?: { variant?: 'default' | 'soft' }
  // etc.
}

Set default props for components at the theme level, reducing repetition across the app.

6. Animation Control

reducedMotion: boolean | 'system'
transitionDuration: 'none' | 'fast' | 'default' | 'slow'

Respect user accessibility preferences and allow global animation speed control.

7. Nested Appearance Mode

appearance: 'light' | 'dark' | 'inherit'  // Per-subtree theming

Allows nested theme contexts with different modes (e.g., dark sidebar in light app).

8. Panel Background Mode

panelBackground: 'solid' | 'translucent'  // For glassmorphism effects

Support for modern translucent/blur backgrounds on panels, cards, and overlays.

9. Cursor Token System

Add cursor CSS variables for global control over cursor styles on interactive components:

cursors?: {
  button?: string
  checkbox?: string
  disabled?: string
  link?: string
  slider?: string
  switch?: string
}

Exposed as CSS variables (--rs-cursor-button, --rs-cursor-checkbox, --rs-cursor-disabled, etc.) so teams can globally customize cursor behavior (e.g., pointer on buttons vs default).

10. Auto-Paired Gray + Accent Colors

Automatically pair accent colors with complementary gray scales when no explicit grayColor is set:

• indigo / iris / violet → slate
• mint / teal / cyan → sage
• orange / amber → mauve
• crimson / pink → mauve

This provides better visual harmony out of the box while still allowing manual override.

Suggested Interface

interface ThemeProviderProps {
  // Existing
  theme?: 'light' | 'dark' | 'system'
  style?: 'modern' | 'traditional'
  accentColor?: 'indigo' | 'orange' | 'mint' | string
  grayColor?: 'gray' | 'mauve' | 'slate' | 'sage'
  
  // New capabilities
  scaling?: 'compact' | 'default' | 'comfortable' | 'spacious'
  radius?: 'none' | 'small' | 'medium' | 'large' | 'full'
  reducedMotion?: boolean | 'system'
  transitionDuration?: 'none' | 'fast' | 'default' | 'slow'
  panelBackground?: 'solid' | 'translucent'
  cursors?: Partial<CursorTokens>
  
  // Advanced customization
  tokens?: DeepPartial<DesignTokens>
  components?: ComponentDefaults
  
  // Configuration
  storageKey?: string
  disableTransitionOnChange?: boolean
}

Implementation Notes

• All new props should have sensible defaults to maintain backward compatibility
• CSS variables should be the primary mechanism for runtime theming
• Consider generating CSS at build time for static themes to improve performance

[ravisuhag]

How these features interact with style

Been thinking about how all these new props would work alongside the existing style prop. Here's my mental model:

Precedence (lowest to highest):

1. style (modern/traditional) - sets the base
2. Feature props (scaling, radius, etc) - override specific aspects
3. Custom tokens - override everything

Quick breakdown

• Scaling - works the same for both styles
• Radius - if you set it explicitly, it overrides whatever the style defines. Otherwise you get the style's default
• Typography - style sets the defaults, but you can override individual fonts
• Tokens - always wins, overrides everything
• Component defaults, reduced motion, appearance - these are independent of style
• Panel background - might want different translucent effects per style

Radius example

/* style sets the base */
[data-style="modern"] { --rs-radius-2: 4px; }
[data-style="traditional"] { --rs-radius-2: 16px; }

/* explicit radius prop overrides */
[data-radius="none"] { --rs-radius-2: 0px; }
[data-radius="full"] { --rs-radius-2: 9999px; }

Approach

I think features should use absolute values rather than being relative to the style. So radius="small" always means 4px whether you're using modern or traditional. Keeps things predictable. If someone needs style-relative adjustments, they can use custom tokens.

Data attributes would look like

<html 
  data-theme="dark"
  data-style="modern"
  data-accent-color="indigo"
  data-scaling="compact"
  data-radius="medium"
  data-panel-bg="translucent"
  data-reduced-motion="true"
>

CSS specificity: :root → [data-style] → [data-scaling] → [data-radius] → [data-theme] → [data-accent-color][data-theme]

[ravisuhag]

Additional features for style flexibility

Was thinking about whether these features would let us build really different looking UIs - from clean/minimal to bold/expressive. Found a few gaps.

1. Custom accent colors

We only have indigo/orange/mint as presets. Most production apps need their own brand color. Should allow custom colors that auto-generate the full scale:

accentColor?: 'indigo' | 'orange' | 'mint' | string  // allow hex/hsl

2. Shadow style

Right now shadows are neutral grays. Some UIs benefit from shadows that pick up a subtle tint of the accent color, and others want full glow effects:

shadowStyle?: 'neutral' | 'colored' | 'glow'

3. Border style

Similar idea - solid borders work for most cases, subtle for minimal UIs, and glow for more expressive styles:

borderStyle?: 'solid' | 'subtle' | 'glow'

4. Animation style

Beyond just reduced motion, different UIs need different animation feels. Some apps want minimal motion, others want more personality:

animationStyle?: 'subtle' | 'expressive'

Updated interface

interface ThemeProviderProps {
  // ... existing props ...
  
  accentColor?: BuiltInAccent | string
  shadowStyle?: 'neutral' | 'colored' | 'glow'
  borderStyle?: 'solid' | 'subtle' | 'glow'
  animationStyle?: 'subtle' | 'expressive'
}

This should cover most UI styles people might want to build.

[ravisuhag]

Phase 1 — Quick wins:

• Radius control
• Border style
• Panel background
• Reduced motion

Phase 2 — Medium effort:

• Scaling/Density
• Animation style (add tokens)
• Shadow style (add RGB colors first)
• Custom token overrides

Phase 3 — Heavy lifting:

• Nested appearance
• Typography scale
• Component defaults
• Custom accent color (consider using culori library)

[rohanchkrabrty]

Completed with #893