kasy-cli 1.21.9 → 1.22.0

package/templates/firebase/lib/features/home/design_system_page.dart

@@ -1,3 +1,5 @@
+import 'dart:ui' show ImageFilter;
+
 import 'package:flutter/material.dart';
 import 'package:kasy_kit/components/kasy_app_bar.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
@@ -33,6 +35,10 @@ class DesignSystemPage extends StatelessWidget {
                 SizedBox(height: KasySpacing.md),
                 _TypographySection(),
                 SizedBox(height: KasySpacing.xl),
+                _SectionHeader('Effect Styles'),
+                SizedBox(height: KasySpacing.md),
+                _EffectsSection(),
+                SizedBox(height: KasySpacing.xl),
                 _SectionHeader('Spacing'),
                 SizedBox(height: KasySpacing.md),
                 _SpacingSection(),
@@ -90,127 +96,513 @@ class _TokenDivider extends StatelessWidget {
 // Colors
 // ---------------------------------------------------------------------------
 
+/// Accessor that reads one token from a [KasyColors] theme (light or dark).
+typedef _Pick = Color Function(KasyColors c);
+
+class _Variant {
+  final String name;
+  final _Pick pick;
+
+  /// Force a hairline border on the swatch (for near-surface / transparent tones).
+  final bool border;
+  const _Variant(this.name, this.pick, {this.border = false});
+}
+
 class _ColorsSection extends StatelessWidget {
   const _ColorsSection();
 
   @override
   Widget build(BuildContext context) {
-    final c = context.colors;
+    return const Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        _ColorsIntro(),
+        SizedBox(height: KasySpacing.lg),
 
-    final List<_ColorToken> brandTokens = [
-      _ColorToken('primary', c.primary),
-      _ColorToken('onPrimary', c.onPrimary, border: true),
-    ];
-    final List<_ColorToken> semanticTokens = [
-      _ColorToken('success', c.success),
-      _ColorToken('onSuccess', c.onSuccess, border: true),
-      _ColorToken('warning', c.warning),
-      _ColorToken('onWarning', c.onWarning, border: true),
-      _ColorToken('error', c.error),
-      _ColorToken('onError', c.onError, border: true),
-    ];
-    final List<_ColorToken> backgroundTokens = [
-      _ColorToken('background', c.background, border: true),
-      _ColorToken('surface', c.surface, border: true),
-      _ColorToken('surfacePrimarySoft', c.surfacePrimarySoft),
-      _ColorToken('surfaceNeutralSoft', c.surfaceNeutralSoft),
-      _ColorToken('surfaceErrorSoft', c.surfaceErrorSoft),
-    ];
-    final List<_ColorToken> contentTokens = [
-      _ColorToken('onBackground', c.onBackground),
-      _ColorToken('onSurface', c.onSurface),
-      _ColorToken('muted', c.muted),
-      _ColorToken('outline', c.outline, border: true),
-      _ColorToken('outlineButton', c.outlineButton, border: true),
-    ];
-    final List<_ColorToken> greyTokens = [
-      _ColorToken('grey1', c.grey1),
-      _ColorToken('grey2', c.grey2),
-      _ColorToken('grey3', c.grey3),
-    ];
-    final List<_ColorToken> fieldTokens = [
-      _ColorToken('onSurface (label)', c.onSurface),
-      _ColorToken('onSurface 54% (helper)', c.onSurface.withValues(alpha: 0.54)),
-      _ColorToken('onSurface 45% (hint)', c.onSurface.withValues(alpha: 0.45)),
-      _ColorToken('onSurface 62% (icon)', c.onSurface.withValues(alpha: 0.62)),
-    ];
-    final List<_ColorToken> avatarTokens = [
-      _ColorToken('avatarFallbackFill', c.avatarFallbackFill),
-    ];
-    final List<_ColorToken> premiumTokens = [
-      _ColorToken('premiumOverlayMid', c.premiumOverlayMid),
-      _ColorToken('premiumOverlayDark', c.premiumOverlayDark),
-      _ColorToken('premiumBannerText', c.premiumBannerText),
-    ];
+        // --- Semantic roles (solid + soft preview) ---
+        _SemanticCategory(
+          name: 'Accent',
+          description:
+              'The primary brand identity. Used sparingly for key actions, '
+              'highlights and moments of emphasis.',
+          base: _pickAccent,
+          onColor: _pickAccentForeground,
+          soft: _pickAccentSoft,
+          softForeground: _pickAccentSoftForeground,
+          variants: [
+            _Variant('accent', _pickAccent),
+            _Variant('accent-hover', _pickAccentHover),
+            _Variant('accent-foreground', _pickAccentForeground, border: true),
+            _Variant('accent-soft', _pickAccentSoft, border: true),
+            _Variant('accent-soft-hover', _pickAccentSoftHover, border: true),
+            _Variant('accent-soft-foreground', _pickAccentSoftForeground),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SemanticCategory(
+          name: 'Default',
+          description:
+              'The neutral backbone of the system. Used for most '
+              'non-emphasized UI elements.',
+          base: _pickNeutral,
+          onColor: _pickNeutralForeground,
+          variants: [
+            _Variant('default', _pickNeutral, border: true),
+            _Variant('default-hover', _pickNeutralHover, border: true),
+            _Variant('default-foreground', _pickNeutralForeground),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SemanticCategory(
+          name: 'Success',
+          description:
+              'Communicates positive outcomes, confirmations and completed '
+              'states.',
+          base: _pickSuccess,
+          onColor: _pickSuccessForeground,
+          soft: _pickSuccessSoft,
+          softForeground: _pickSuccessSoftForeground,
+          variants: [
+            _Variant('success', _pickSuccess),
+            _Variant('success-hover', _pickSuccessHover),
+            _Variant('success-foreground', _pickSuccessForeground, border: true),
+            _Variant('success-soft', _pickSuccessSoft, border: true),
+            _Variant('success-soft-hover', _pickSuccessSoftHover, border: true),
+            _Variant('success-soft-foreground', _pickSuccessSoftForeground),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SemanticCategory(
+          name: 'Warning',
+          description:
+              'Indicates caution or risk that requires attention but is not '
+              'destructive.',
+          base: _pickWarning,
+          onColor: _pickWarningForeground,
+          soft: _pickWarningSoft,
+          softForeground: _pickWarningSoftForeground,
+          variants: [
+            _Variant('warning', _pickWarning),
+            _Variant('warning-hover', _pickWarningHover),
+            _Variant('warning-foreground', _pickWarningForeground, border: true),
+            _Variant('warning-soft', _pickWarningSoft, border: true),
+            _Variant('warning-soft-hover', _pickWarningSoftHover, border: true),
+            _Variant('warning-soft-foreground', _pickWarningSoftForeground),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SemanticCategory(
+          name: 'Danger',
+          description:
+              'Represents destructive, irreversible or critical actions and '
+              'states.',
+          base: _pickDanger,
+          onColor: _pickDangerForeground,
+          soft: _pickDangerSoft,
+          softForeground: _pickDangerSoftForeground,
+          variants: [
+            _Variant('danger', _pickDanger),
+            _Variant('danger-hover', _pickDangerHover),
+            _Variant('danger-foreground', _pickDangerForeground, border: true),
+            _Variant('danger-soft', _pickDangerSoft, border: true),
+            _Variant('danger-soft-hover', _pickDangerSoftHover, border: true),
+            _Variant('danger-soft-foreground', _pickDangerSoftForeground),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
 
-    return _TokenCard(
-      children: [
-        const _ColorGroupLabel('Brand'),
-        ..._buildColorRows(context, brandTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Semantic'),
-        ..._buildColorRows(context, semanticTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Background & Surface'),
-        ..._buildColorRows(context, backgroundTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Content'),
-        ..._buildColorRows(context, contentTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Grey Scale'),
-        ..._buildColorRows(context, greyTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Field'),
-        ..._buildColorRows(context, fieldTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Avatar'),
-        ..._buildColorRows(context, avatarTokens),
-        const _TokenDivider(),
-        const _ColorGroupLabel('Premium'),
-        ..._buildColorRows(context, premiumTokens),
+        // --- Neutral swatch roles ---
+        _SwatchCategory(
+          name: 'Foreground',
+          description:
+              'Primary content such as text and icons. Adapts automatically to '
+              'background and surface contexts.',
+          variants: [
+            _Variant('foreground', _pickForeground),
+            _Variant('muted', _pickForegroundMuted),
+            _Variant('segment', _pickForegroundSegment),
+            _Variant('overlay', _pickForegroundOverlay),
+            _Variant('link', _pickForegroundLink),
+            _Variant('inverse', _pickForegroundInverse, border: true),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SwatchCategory(
+          name: 'Background',
+          description:
+              'The base canvas of the interface. Establishes overall contrast '
+              'and mood while staying visually quiet.',
+          variants: [
+            _Variant('background', _pickBackground, border: true),
+            _Variant('background-secondary', _pickBackgroundSecondary, border: true),
+            _Variant('background-tertiary', _pickBackgroundTertiary, border: true),
+            _Variant('background-inverse', _pickBackgroundInverse),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SwatchCategory(
+          name: 'Surface',
+          description:
+              'Containers such as cards, panels, modals and dropdowns. Create '
+              'separation through elevation and layering.',
+          variants: [
+            _Variant('surface', _pickSurface, border: true),
+            _Variant('surface-secondary', _pickSurfaceSecondary, border: true),
+            _Variant('surface-tertiary', _pickSurfaceTertiary, border: true),
+            _Variant('surface-transparent', _pickSurfaceTransparent, border: true),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SwatchCategory(
+          name: 'Form field',
+          description:
+              'Specialized tokens for inputs and controls, accounting for '
+              'default, hover and focus states.',
+          variants: [
+            _Variant('field-background', _pickFieldBackground, border: true),
+            _Variant('field-background-hover', _pickFieldBackgroundHover, border: true),
+            _Variant('field-background-focus', _pickFieldBackgroundFocus, border: true),
+            _Variant('field-placeholder', _pickFieldPlaceholder),
+            _Variant('field-foreground', _pickFieldForeground),
+            _Variant('field-border', _pickFieldBorder, border: true),
+            _Variant('field-border-hover', _pickFieldBorderHover, border: true),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SwatchCategory(
+          name: 'Separator',
+          description:
+              'Dividers, outlines and subtle boundaries. Low contrast and '
+              'unobtrusive by design.',
+          variants: [
+            _Variant('separator', _pickSeparator, border: true),
+            _Variant('separator-secondary', _pickSeparatorSecondary, border: true),
+            _Variant('separator-tertiary', _pickSeparatorTertiary, border: true),
+          ],
+        ),
+        SizedBox(height: KasySpacing.xl),
+        _SwatchCategory(
+          name: 'Other',
+          description:
+              'Shared utility tokens used for borders, overlays, segmented '
+              'controls and backdrops.',
+          variants: [
+            _Variant('border', _pickBorder, border: true),
+            _Variant('overlay', _pickOverlay, border: true),
+            _Variant('segment', _pickSegment, border: true),
+            _Variant('backdrop', _pickBackdrop, border: true),
+          ],
+        ),
       ],
     );
   }
+}
+
+// --- Token accessors (kept top-level so the section tree stays const) ---
+Color _pickAccent(KasyColors c) => c.accent;
+Color _pickAccentHover(KasyColors c) => c.accentHover;
+Color _pickAccentForeground(KasyColors c) => c.accentForeground;
+Color _pickAccentSoft(KasyColors c) => c.accentSoft;
+Color _pickAccentSoftHover(KasyColors c) => c.accentSoftHover;
+Color _pickAccentSoftForeground(KasyColors c) => c.accentSoftForeground;
+Color _pickNeutral(KasyColors c) => c.neutral;
+Color _pickNeutralHover(KasyColors c) => c.neutralHover;
+Color _pickNeutralForeground(KasyColors c) => c.neutralForeground;
+Color _pickSuccess(KasyColors c) => c.success;
+Color _pickSuccessHover(KasyColors c) => c.successHover;
+Color _pickSuccessForeground(KasyColors c) => c.successForeground;
+Color _pickSuccessSoft(KasyColors c) => c.successSoft;
+Color _pickSuccessSoftHover(KasyColors c) => c.successSoftHover;
+Color _pickSuccessSoftForeground(KasyColors c) => c.successSoftForeground;
+Color _pickWarning(KasyColors c) => c.warning;
+Color _pickWarningHover(KasyColors c) => c.warningHover;
+Color _pickWarningForeground(KasyColors c) => c.warningForeground;
+Color _pickWarningSoft(KasyColors c) => c.warningSoft;
+Color _pickWarningSoftHover(KasyColors c) => c.warningSoftHover;
+Color _pickWarningSoftForeground(KasyColors c) => c.warningSoftForeground;
+Color _pickDanger(KasyColors c) => c.danger;
+Color _pickDangerHover(KasyColors c) => c.dangerHover;
+Color _pickDangerForeground(KasyColors c) => c.dangerForeground;
+Color _pickDangerSoft(KasyColors c) => c.dangerSoft;
+Color _pickDangerSoftHover(KasyColors c) => c.dangerSoftHover;
+Color _pickDangerSoftForeground(KasyColors c) => c.dangerSoftForeground;
+Color _pickForeground(KasyColors c) => c.foreground;
+Color _pickForegroundMuted(KasyColors c) => c.foregroundMuted;
+Color _pickForegroundSegment(KasyColors c) => c.foregroundSegment;
+Color _pickForegroundOverlay(KasyColors c) => c.foregroundOverlay;
+Color _pickForegroundLink(KasyColors c) => c.foregroundLink;
+Color _pickForegroundInverse(KasyColors c) => c.foregroundInverse;
+Color _pickBackground(KasyColors c) => c.background;
+Color _pickBackgroundSecondary(KasyColors c) => c.backgroundSecondary;
+Color _pickBackgroundTertiary(KasyColors c) => c.backgroundTertiary;
+Color _pickBackgroundInverse(KasyColors c) => c.backgroundInverse;
+Color _pickSurface(KasyColors c) => c.surface;
+Color _pickSurfaceSecondary(KasyColors c) => c.surfaceSecondary;
+Color _pickSurfaceTertiary(KasyColors c) => c.surfaceTertiary;
+Color _pickSurfaceTransparent(KasyColors c) => c.surfaceTransparent;
+Color _pickFieldBackground(KasyColors c) => c.fieldBackground;
+Color _pickFieldBackgroundHover(KasyColors c) => c.fieldBackgroundHover;
+Color _pickFieldBackgroundFocus(KasyColors c) => c.fieldBackgroundFocus;
+Color _pickFieldPlaceholder(KasyColors c) => c.fieldPlaceholder;
+Color _pickFieldForeground(KasyColors c) => c.fieldForeground;
+Color _pickFieldBorder(KasyColors c) => c.fieldBorder;
+Color _pickFieldBorderHover(KasyColors c) => c.fieldBorderHover;
+Color _pickSeparator(KasyColors c) => c.separator;
+Color _pickSeparatorSecondary(KasyColors c) => c.separatorSecondary;
+Color _pickSeparatorTertiary(KasyColors c) => c.separatorTertiary;
+Color _pickBorder(KasyColors c) => c.border;
+Color _pickOverlay(KasyColors c) => c.overlay;
+Color _pickSegment(KasyColors c) => c.segment;
+Color _pickBackdrop(KasyColors c) => c.backdrop;
+
+String _hexOf(Color color) {
+  final int v = color.toARGB32();
+  final int a = (v >> 24) & 0xFF;
+  final int r = (v >> 16) & 0xFF;
+  final int g = (v >> 8) & 0xFF;
+  final int b = v & 0xFF;
+  String two(int x) => x.toRadixString(16).padLeft(2, '0').toUpperCase();
+  final String rgb = '${two(r)}${two(g)}${two(b)}';
+  return a == 0xFF ? '#$rgb' : '#$rgb${two(a)}';
+}
+
+// ---------------------------------------------------------------------------
+// Colors — intro
+// ---------------------------------------------------------------------------
+
+class _ColorsIntro extends StatelessWidget {
+  const _ColorsIntro();
 
-  List<Widget> _buildColorRows(BuildContext context, List<_ColorToken> tokens) {
-    return tokens.map((t) => _ColorRow(token: t)).toList();
+  @override
+  Widget build(BuildContext context) {
+    return Text(
+      'Built around semantic intent, not raw palettes. A small set of color '
+      'roles covers most interface needs, each resolving to a light and a dark '
+      'theme shown side by side.',
+      style: context.textTheme.bodyMedium?.copyWith(
+        color: context.colors.muted,
+        height: 1.5,
+      ),
+    );
   }
 }
 
-class _ColorToken {
+// ---------------------------------------------------------------------------
+// Category heading (name + description)
+// ---------------------------------------------------------------------------
+
+class _CategoryHeading extends StatelessWidget {
   final String name;
-  final Color color;
-  final bool border;
-  const _ColorToken(this.name, this.color, {this.border = false});
+  final String description;
+  const _CategoryHeading({required this.name, required this.description});
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        Text(
+          name,
+          style: context.textTheme.titleMedium?.copyWith(
+            color: context.colors.onSurface,
+            fontWeight: FontWeight.w700,
+          ),
+        ),
+        const SizedBox(height: KasySpacing.xs),
+        Text(
+          description,
+          style: context.textTheme.bodySmall?.copyWith(
+            color: context.colors.muted,
+            height: 1.45,
+          ),
+        ),
+        const SizedBox(height: KasySpacing.smd),
+      ],
+    );
+  }
 }
 
-class _ColorGroupLabel extends StatelessWidget {
+// ---------------------------------------------------------------------------
+// Semantic category: heading + Light/Dark solid+soft preview + variant list
+// ---------------------------------------------------------------------------
+
+class _SemanticCategory extends StatelessWidget {
+  final String name;
+  final String description;
+  final _Pick base;
+  final _Pick onColor;
+  final _Pick? soft;
+  final _Pick? softForeground;
+  final List<_Variant> variants;
+
+  const _SemanticCategory({
+    required this.name,
+    required this.description,
+    required this.base,
+    required this.onColor,
+    required this.variants,
+    this.soft,
+    this.softForeground,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        _CategoryHeading(name: name, description: description),
+        Row(
+          children: [
+            Expanded(child: _SemanticPreview(theme: KasyColors.light(), label: 'Light', base: base, onColor: onColor, soft: soft, softForeground: softForeground)),
+            const SizedBox(width: KasySpacing.smd),
+            Expanded(child: _SemanticPreview(theme: KasyColors.dark(), label: 'Dark', base: base, onColor: onColor, soft: soft, softForeground: softForeground)),
+          ],
+        ),
+        const SizedBox(height: KasySpacing.smd),
+        _VariantList(variants: variants),
+      ],
+    );
+  }
+}
+
+class _SemanticPreview extends StatelessWidget {
+  final KasyColors theme;
   final String label;
-  const _ColorGroupLabel(this.label);
+  final _Pick base;
+  final _Pick onColor;
+  final _Pick? soft;
+  final _Pick? softForeground;
+
+  const _SemanticPreview({
+    required this.theme,
+    required this.label,
+    required this.base,
+    required this.onColor,
+    required this.soft,
+    required this.softForeground,
+  });
 
   @override
   Widget build(BuildContext context) {
-    return Padding(
-      padding: const EdgeInsets.fromLTRB(KasySpacing.md, KasySpacing.smd, KasySpacing.md, KasySpacing.xs),
+    return Container(
+      padding: const EdgeInsets.all(KasySpacing.smd),
+      decoration: BoxDecoration(
+        color: theme.surface,
+        borderRadius: BorderRadius.circular(KasyRadius.md),
+        border: Border.all(color: theme.border),
+      ),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        children: [
+          Text(
+            label,
+            style: context.textTheme.labelSmall?.copyWith(
+              color: theme.foregroundMuted,
+              letterSpacing: 0.6,
+            ),
+          ),
+          const SizedBox(height: KasySpacing.sm),
+          _PreviewPill(bg: base(theme), fg: onColor(theme), text: 'Solid'),
+          if (soft != null && softForeground != null) ...[
+            const SizedBox(height: KasySpacing.sm),
+            _PreviewPill(bg: soft!(theme), fg: softForeground!(theme), text: 'Soft'),
+          ],
+        ],
+      ),
+    );
+  }
+}
+
+class _PreviewPill extends StatelessWidget {
+  final Color bg;
+  final Color fg;
+  final String text;
+  const _PreviewPill({required this.bg, required this.fg, required this.text});
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      height: 36,
+      alignment: Alignment.center,
+      decoration: BoxDecoration(
+        color: bg,
+        borderRadius: BorderRadius.circular(KasyRadius.sm),
+      ),
       child: Text(
-        label,
-        style: context.textTheme.labelSmall?.copyWith(
-          color: context.colors.muted,
-          letterSpacing: 0.6,
+        text,
+        style: context.textTheme.labelMedium?.copyWith(
+          color: fg,
+          fontWeight: FontWeight.w600,
         ),
       ),
     );
   }
 }
 
-class _ColorRow extends StatelessWidget {
-  final _ColorToken token;
-  const _ColorRow({required this.token});
+// ---------------------------------------------------------------------------
+// Swatch category: heading + variant list (Light/Dark chips)
+// ---------------------------------------------------------------------------
+
+class _SwatchCategory extends StatelessWidget {
+  final String name;
+  final String description;
+  final List<_Variant> variants;
+
+  const _SwatchCategory({
+    required this.name,
+    required this.description,
+    required this.variants,
+  });
 
   @override
   Widget build(BuildContext context) {
-    final String hex =
-        '#${token.color.toARGB32().toRadixString(16).substring(2).toUpperCase()}';
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        _CategoryHeading(name: name, description: description),
+        _VariantList(variants: variants),
+      ],
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Variant list (one row per token: Light chip, Dark chip, name, hex pair)
+// ---------------------------------------------------------------------------
+
+class _VariantList extends StatelessWidget {
+  final List<_Variant> variants;
+  const _VariantList({required this.variants});
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors light = KasyColors.light();
+    final KasyColors dark = KasyColors.dark();
+    return _TokenCard(
+      children: [
+        for (int i = 0; i < variants.length; i++) ...[
+          _VariantRow(variant: variants[i], light: light, dark: dark),
+          if (i < variants.length - 1) const _TokenDivider(),
+        ],
+      ],
+    );
+  }
+}
+
+class _VariantRow extends StatelessWidget {
+  final _Variant variant;
+  final KasyColors light;
+  final KasyColors dark;
+  const _VariantRow({
+    required this.variant,
+    required this.light,
+    required this.dark,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final Color lightColor = variant.pick(light);
+    final Color darkColor = variant.pick(dark);
     return Padding(
       padding: const EdgeInsets.symmetric(
         horizontal: KasySpacing.md,
@@ -218,33 +610,29 @@ class _ColorRow extends StatelessWidget {
       ),
       child: Row(
         children: [
-          Container(
-            width: 28,
-            height: 28,
-            decoration: BoxDecoration(
-              color: token.color,
-              borderRadius: BorderRadius.circular(KasyRadius.xs),
-              border: token.border
-                  ? Border.all(
-                      color: context.colors.outline.withValues(alpha: 0.5),
-                    )
-                  : null,
-            ),
-          ),
+          _ThemeChip(surface: light.surface, token: lightColor, border: variant.border),
+          const SizedBox(width: KasySpacing.xs),
+          _ThemeChip(surface: dark.surface, token: darkColor, border: variant.border),
           const SizedBox(width: KasySpacing.smd),
           Expanded(
-            child: Text(
-              token.name,
-              style: context.textTheme.bodyMedium?.copyWith(
-                color: context.colors.onSurface,
-              ),
-            ),
-          ),
-          Text(
-            hex,
-            style: context.textTheme.bodySmall?.copyWith(
-              color: context.colors.muted,
-              fontFeatures: const [FontFeature.tabularFigures()],
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text(
+                  variant.name,
+                  style: context.textTheme.bodyMedium?.copyWith(
+                    color: context.colors.onSurface,
+                  ),
+                ),
+                const SizedBox(height: 2),
+                Text(
+                  '${_hexOf(lightColor)}  ·  ${_hexOf(darkColor)}',
+                  style: context.textTheme.bodySmall?.copyWith(
+                    color: context.colors.muted,
+                    fontFeatures: const [FontFeature.tabularFigures()],
+                  ),
+                ),
+              ],
             ),
           ),
         ],
@@ -253,6 +641,40 @@ class _ColorRow extends StatelessWidget {
   }
 }
 
+class _ThemeChip extends StatelessWidget {
+  final Color surface;
+  final Color token;
+  final bool border;
+  const _ThemeChip({
+    required this.surface,
+    required this.token,
+    this.border = false,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      width: 28,
+      height: 28,
+      padding: const EdgeInsets.all(3),
+      decoration: BoxDecoration(
+        color: surface,
+        borderRadius: BorderRadius.circular(KasyRadius.xs),
+        border: Border.all(color: context.colors.outline.withValues(alpha: 0.5)),
+      ),
+      child: DecoratedBox(
+        decoration: BoxDecoration(
+          color: token,
+          borderRadius: BorderRadius.circular(KasyRadius.xs - 1),
+          border: border
+              ? Border.all(color: context.colors.outline.withValues(alpha: 0.5))
+              : null,
+        ),
+      ),
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Typography
 // ---------------------------------------------------------------------------
@@ -262,76 +684,82 @@ class _TypographySection extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    final tt = context.textTheme;
-    final ktt = KasyTextTheme.build();
-
-    final List<_TypeToken> tokens = [
-      _TypeToken('displayLarge', tt.displayLarge, ktt.displayLarge),
-      _TypeToken('displayMedium', tt.displayMedium, ktt.displayMedium),
-      _TypeToken('displaySmall', tt.displaySmall, ktt.displaySmall),
-      _TypeToken('headlineLarge', tt.headlineLarge, ktt.headlineLarge),
-      _TypeToken('headlineMedium', tt.headlineMedium, ktt.headlineMedium),
-      _TypeToken('headlineSmall', tt.headlineSmall, ktt.headlineSmall),
-      _TypeToken('titleLarge', tt.titleLarge, ktt.titleLarge),
-      _TypeToken('titleMedium', tt.titleMedium, ktt.titleMedium),
-      _TypeToken('titleSmall', tt.titleSmall, ktt.titleSmall),
-      _TypeToken('bodyLarge', tt.bodyLarge, ktt.bodyLarge),
-      _TypeToken('bodyMedium', tt.bodyMedium, ktt.bodyMedium),
-      _TypeToken('bodySmall', tt.bodySmall, ktt.bodySmall),
-      _TypeToken('labelLarge', tt.labelLarge, ktt.labelLarge),
-      _TypeToken('labelMedium', tt.labelMedium, ktt.labelMedium),
-      _TypeToken('labelSmall', tt.labelSmall, ktt.labelSmall),
+    final Color fg = context.colors.onSurface;
+    final List<_TypeRole> roles = [
+      _TypeRole('Heading 1', KasyTextTheme.heading1, 'ExtraBold · 36/40'),
+      _TypeRole('Heading 2', KasyTextTheme.heading2, 'Bold · 24/32'),
+      _TypeRole('Heading 3', KasyTextTheme.heading3, 'SemiBold · 20/28'),
+      _TypeRole('Heading 4', KasyTextTheme.heading4, 'SemiBold · 16/24'),
+      _TypeRole('Body base', KasyTextTheme.bodyBase, 'Regular · 16/24'),
+      _TypeRole('Body base medium', KasyTextTheme.bodyBaseMedium, 'Medium · 16/24'),
+      _TypeRole('Body sm', KasyTextTheme.bodySm, 'Regular · 14/20'),
+      _TypeRole('Body sm medium', KasyTextTheme.bodySmMedium, 'Medium · 14/20'),
+      _TypeRole('Body xs', KasyTextTheme.bodyXs, 'Regular · 12/16'),
+      _TypeRole('Body xs medium', KasyTextTheme.bodyXsMedium, 'Medium · 12/16'),
+      _TypeRole('Link base', KasyTextTheme.linkBase, 'Medium · 16/24 · Underlined'),
+      _TypeRole('Link sm', KasyTextTheme.linkSm, 'Medium · 14/20 · Underlined'),
+      _TypeRole('Text field base', KasyTextTheme.textFieldBase, 'Regular · 16/24'),
+      _TypeRole('Text field sm', KasyTextTheme.textFieldSm, 'Regular · 14/20'),
+      _TypeRole('Button base', KasyTextTheme.buttonBase, 'Medium · 16/24'),
+      _TypeRole('Button sm', KasyTextTheme.buttonSm, 'Medium · 14/20'),
     ];
 
-    return _TokenCard(
-      children: tokens
-          .map(
-            (t) => Column(
-              mainAxisSize: MainAxisSize.min,
-              children: [
-                _TypeRow(token: t),
-                if (t != tokens.last) const _TokenDivider(),
-              ],
-            ),
-          )
-          .toList(),
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        Text(
+          "Based on Tailwind's scale: Inter, neutral tracking and predictable "
+          'rhythm. Functional and scalable rather than decorative.',
+          style: context.textTheme.bodyMedium?.copyWith(
+            color: context.colors.muted,
+            height: 1.5,
+          ),
+        ),
+        const SizedBox(height: KasySpacing.md),
+        _TokenCard(
+          children: [
+            for (int i = 0; i < roles.length; i++) ...[
+              _TypeRow(role: roles[i], foreground: fg),
+              if (i < roles.length - 1) const _TokenDivider(),
+            ],
+          ],
+        ),
+      ],
     );
   }
 }
 
-class _TypeToken {
+class _TypeRole {
   final String name;
-  final TextStyle? style;
-  final TextStyle raw;
-  const _TypeToken(this.name, this.style, this.raw);
+  final TextStyle style;
+  final String spec;
+  const _TypeRole(this.name, this.style, this.spec);
 }
 
 class _TypeRow extends StatelessWidget {
-  final _TypeToken token;
-  const _TypeRow({required this.token});
+  final _TypeRole role;
+  final Color foreground;
+  const _TypeRow({required this.role, required this.foreground});
 
   @override
   Widget build(BuildContext context) {
-    final double size = token.raw.fontSize ?? 14;
-    final int weight = token.raw.fontWeight?.value ?? 400;
     return Padding(
       padding: const EdgeInsets.symmetric(
         horizontal: KasySpacing.md,
         vertical: KasySpacing.smd,
       ),
-      child: Row(
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
         children: [
-          Expanded(
-            child: Text(
-              token.name,
-              style: token.style,
-              maxLines: 1,
-              overflow: TextOverflow.ellipsis,
-            ),
+          Text(
+            role.name,
+            style: role.style.copyWith(color: foreground),
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
           ),
-          const SizedBox(width: KasySpacing.md),
+          const SizedBox(height: 4),
           Text(
-            '${size.toInt()}/$weight',
+            'Inter · ${role.spec}',
             style: context.textTheme.bodySmall?.copyWith(
               color: context.colors.muted,
               fontFeatures: const [FontFeature.tabularFigures()],
@@ -436,12 +864,17 @@ class _RadiusSection extends StatelessWidget {
   const _RadiusSection();
 
   static const List<({String name, double value})> _tokens = [
-    (name: 'xs', value: KasyRadius.xs),
-    (name: 'sm', value: KasyRadius.sm),
-    (name: 'md', value: KasyRadius.md),
-    (name: 'lg', value: KasyRadius.lg),
-    (name: 'xl', value: KasyRadius.xl),
-    (name: 'full', value: 999),
+    (name: 'none', value: KasyRadius.roundedNone),
+    (name: 'xs', value: KasyRadius.roundedXs),
+    (name: 'sm', value: KasyRadius.roundedSm),
+    (name: 'md', value: KasyRadius.roundedMd),
+    (name: 'lg', value: KasyRadius.roundedLg),
+    (name: 'xl', value: KasyRadius.roundedXl),
+    (name: '2xl', value: KasyRadius.rounded2xl),
+    (name: '2.5xl', value: KasyRadius.rounded2_5xl),
+    (name: '3xl', value: KasyRadius.rounded3xl),
+    (name: '4xl', value: KasyRadius.rounded4xl),
+    (name: 'full', value: KasyRadius.roundedFull),
   ];
 
   @override
@@ -550,3 +983,208 @@ class _TokenCard extends StatelessWidget {
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Effect Styles — Shadows, Blur, Focus Rings
+// ---------------------------------------------------------------------------
+
+class _EffectsSection extends StatelessWidget {
+  const _EffectsSection();
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        Text(
+          'How depth, separation and focus are expressed. Applied consistently '
+          'to communicate hierarchy without relying on color alone.',
+          style: context.textTheme.bodyMedium?.copyWith(
+            color: context.colors.muted,
+            height: 1.5,
+          ),
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        const _EffectGroupLabel('Shadows'),
+        const SizedBox(height: KasySpacing.smd),
+        const Wrap(
+          spacing: KasySpacing.md,
+          runSpacing: KasySpacing.md,
+          children: [
+            _ShadowTile(label: 'Inner', shadows: [], inner: true),
+            _ShadowTile(label: 'Surface', shadows: KasyShadows.surface),
+            _ShadowTile(label: 'Field', shadows: KasyShadows.field),
+            _ShadowTile(label: 'Switch', shadows: KasyShadows.switchControl),
+            _ShadowTile(label: 'Tab', shadows: KasyShadows.tab),
+            _ShadowTile(label: 'Overlay', shadows: KasyShadows.overlay),
+          ],
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        const _EffectGroupLabel('Blur'),
+        const SizedBox(height: KasySpacing.smd),
+        const Wrap(
+          spacing: KasySpacing.md,
+          runSpacing: KasySpacing.md,
+          children: [
+            _BlurTile(label: 'Blur', sigma: 8),
+            _BlurTile(label: 'Backdrop', sigma: 3),
+          ],
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        const _EffectGroupLabel('Focus Rings'),
+        const SizedBox(height: KasySpacing.smd),
+        const Wrap(
+          spacing: KasySpacing.lg,
+          runSpacing: KasySpacing.md,
+          children: [
+            _FocusTile(label: 'Focus Ring', field: false),
+            _FocusTile(label: 'Focus Ring Field', field: true),
+          ],
+        ),
+      ],
+    );
+  }
+}
+
+class _EffectGroupLabel extends StatelessWidget {
+  final String label;
+  const _EffectGroupLabel(this.label);
+
+  @override
+  Widget build(BuildContext context) {
+    return Text(
+      label,
+      style: context.textTheme.titleSmall?.copyWith(
+        color: context.colors.onSurface,
+        fontWeight: FontWeight.w700,
+      ),
+    );
+  }
+}
+
+/// 72×72 labeled sample tile shared by the effect groups.
+class _EffectTile extends StatelessWidget {
+  final String label;
+  final Widget box;
+  const _EffectTile({required this.label, required this.box});
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        box,
+        const SizedBox(height: KasySpacing.sm),
+        Text(
+          label,
+          style: context.textTheme.bodySmall?.copyWith(
+            color: context.colors.muted,
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+class _ShadowTile extends StatelessWidget {
+  final String label;
+  final List<BoxShadow> shadows;
+  final bool inner;
+  const _ShadowTile({
+    required this.label,
+    required this.shadows,
+    this.inner = false,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final c = context.colors;
+    return _EffectTile(
+      label: label,
+      box: Container(
+        width: 72,
+        height: 72,
+        decoration: BoxDecoration(
+          color: c.surface,
+          borderRadius: BorderRadius.circular(KasyRadius.md),
+          border: Border.all(color: c.separator),
+          boxShadow: inner ? null : shadows,
+          gradient: inner
+              ? LinearGradient(
+                  begin: Alignment.topCenter,
+                  end: Alignment.center,
+                  colors: [KasyShadows.inner, c.surface],
+                )
+              : null,
+        ),
+      ),
+    );
+  }
+}
+
+class _BlurTile extends StatelessWidget {
+  final String label;
+  final double sigma;
+  const _BlurTile({required this.label, required this.sigma});
+
+  @override
+  Widget build(BuildContext context) {
+    final c = context.colors;
+    return _EffectTile(
+      label: label,
+      box: ClipRRect(
+        borderRadius: BorderRadius.circular(KasyRadius.md),
+        child: SizedBox(
+          width: 72,
+          height: 72,
+          child: Stack(
+            fit: StackFit.expand,
+            children: [
+              DecoratedBox(
+                decoration: BoxDecoration(
+                  gradient: LinearGradient(
+                    begin: Alignment.topLeft,
+                    end: Alignment.bottomRight,
+                    colors: [c.accent, c.success, c.warning, c.danger],
+                  ),
+                ),
+              ),
+              BackdropFilter(
+                filter: ImageFilter.blur(sigmaX: sigma, sigmaY: sigma),
+                child: ColoredBox(
+                  color: c.surface.withValues(alpha: 0.10),
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _FocusTile extends StatelessWidget {
+  final String label;
+  final bool field;
+  const _FocusTile({required this.label, required this.field});
+
+  @override
+  Widget build(BuildContext context) {
+    final c = context.colors;
+    return _EffectTile(
+      label: label,
+      box: Container(
+        width: 72,
+        height: 72,
+        decoration: BoxDecoration(
+          color: c.surface,
+          borderRadius: BorderRadius.circular(KasyRadius.md),
+          border: Border.all(color: c.separator),
+          boxShadow: field
+              ? KasyShadows.focusRingField(ring: c.accent)
+              : KasyShadows.focusRing(ring: c.accent, gap: c.background),
+        ),
+      ),
+    );
+  }
+}