Design System (CoUI)#

Triggers#

• When defining or modifying new design tokens (colors, typography, spacing, motion)
• When customizing CoUI themes
• When configuring or changing CoUI component themes
• When creating or updating design system documentation
• When switching between or comparing 3 design systems (CoUI, M3 Expressive, Liquid Glass)

Actions#

1. Analyze existing design token files in the coui_core package
2. Review theme configuration based on CoreThemeData
3. Create or modify design tokens according to requested changes
4. Verify consistency between Flutter-side coui_flutter and Jaspr Web-side coui_web
5. Confirm that themes are correctly applied to CoUI components

coui_core Design Token Reference#

CoreThemeData (Top-level Theme Object)#

import 'package:coui_core/coui_core.dart';

final theme = CoreThemeData(
  colorScheme: CoreColorScheme(...),   // Required — 36 color tokens
  brightness: CoreBrightness.light,    // Required — light | dark
  designSystem: DesignSystem.coui,  // Required — coui | m3Expressive | liquidGlass
  typography: CoreTypographyScale.material3, // Optional — 30 text styles
  cornerStyle: CornerStyle.rounded,    // Optional — rounded | squircle | glassRounded
  defaultMotion: CoreSpringConfig.standard,  // Optional — animation default
  defaultSurface: CoreSurfaceToken.flat(),   // Optional — surface rendering
  textScaling: 1.0,    // Optional — global text scale
  sizeScaling: 1.0,    // Optional — global size scale
  radiusScaling: 1.0,  // Optional — global radius scale
);

CoreColorScheme (36 Color Tokens)#

CoUI Core (20, required):

• primary, primaryContent
• secondary, secondaryContent
• accent, accentContent
• neutral, neutralContent
• base100, base200, base300, baseContent
• info, infoContent
• success, successContent
• warning, warningContent
• error, errorContent

M3 Expressive Extended (12, nullable):

• tertiary, tertiaryContent
• surfaceContainerLowest, surfaceContainerLow, surfaceContainer, surfaceContainerHigh, surfaceContainerHighest
• outline, outlineVariant
• inverseSurface, inverseOnSurface, inversePrimary

Liquid Glass (4, nullable):

• glassTint, glassHighlight, glassShadow, glassIllumination

final scheme = CoreColorScheme(
  primary: CoreColor.fromHex('#570DF8'),
  primaryContent: CoreColor.fromHex('#FFFFFF'),
  // ... 20 required tokens
);

// Or create from a Map
final scheme = CoreColorScheme.fromMap(colorMap);

CoreTypographyScale (30 Text Styles)#

Baseline (15): displayLarge/Medium/Small, headlineLarge/Medium/Small, titleLarge/Medium/Small, bodyLarge/Medium/Small, labelLarge/Medium/Small

Emphasized (15): Each baseline with Emphasized suffix (heavier font-weight)

final typography = CoreTypographyScale.material3;
final headline = typography.headlineLarge;
// → CoreTextStyle(fontSize: 32, lineHeight: 1.25, fontWeight: 400)
final scaled = typography.scale(0.875); // Overall scale

Spacing (34 Values)#

// Spacing.s0 (0) ~ Spacing.s96 (384)
// Key values: s1(4), s2(8), s3(12), s4(16), s6(24), s8(32), s12(48), s16(64)

CoreRadiusScale (10 Steps + 4 Semantic Aliases)#

// Scale: none(0), extraExtraSmall(2), extraSmall(4), small(8), medium(12),
//         large(16), extraLarge(20), extraExtraLarge(28), extraExtraExtraLarge(32), full(9999)
// Semantic: box(16), field(4), selector(8), badge(9999)

CoreComponentSize#

enum CoreComponentSize { xs, sm, md, lg, xl }

CoreDuration (12 Timing Values)#

// instant(0ms), ultraShort(50ms), xs(100ms), short(150ms),
// normal(200ms), medium(300ms), long(400ms), xl(500ms)
// Semantic: pageTransition, modal(250ms), tooltipDelay, toast(3000ms)

CoreSpringConfig (5 Presets)#

// gentle(damping:0.8, stiffness:200), standard(0.7, 300),
// bouncy(0.5, 400), snappy(0.9, 500), stiff(1.0, 600)

CoreMotionToken (sealed class)#

// CssTransitionMotion — CSS transition based (durationMs + easing)
// SpringMotion — Spring physics based (dampingRatio + stiffness)
// GlassPhysicsMotion — Liquid Glass physics (spring + specularResponse)

CoreSurfaceToken (Surface Rendering)#

CoreSurfaceToken.flat()                          // Flat
CoreSurfaceToken.tonalElevation(elevation: 2)    // M3 tonal elevation (0-5)
CoreSurfaceToken.glass(opacity: 0.3, blur: 20, material: CoreGlassMaterial(...)) // Glass

DesignSystem enum#

enum DesignSystem { coui, m3Expressive, liquidGlass }

Output#

• CoreThemeData-based theme configuration code
• CoreColorScheme definitions (CoUI/M3E/LG layers)
• CoUI CSS theme configuration
• Flutter/Web cross-platform consistency verification results

Notes#

• CoUI consists of 3 packages: coui_core (tokens + contracts), coui_flutter (Flutter implementation), coui_web (Jaspr Web implementation)
• coui_core design tokens are pure Dart objects shared across platforms
• CoUI themes are applied via CSS on the Jaspr Web side and provide various built-in themes
• Flutter-side themes read tokens directly from CoreThemeData and apply them to widgets
• CoreColorScheme.fromMap() and toMap() enable JSON serialization/deserialization
• Use CoreThemeData.copyWith() to create theme variants such as dark mode