illustration-system

name	illustration-system
description	Scalable, theme-aware illustrations for mobile — pipeline, tokenization, and platform delivery. Use this when authoring or shipping illustrations.

Illustration System

Instructions

Illustrations are large, expressive assets. Done right they feel native in both light and dark mode, scale without blur, and ship small. Done wrong they bloat the binary and break on dark backgrounds.

1. Vector-First

Ship SVG source; raster only when there is no alternative (photographic content, complex gradients that fail to render efficiently as vectors).

• Android: VectorDrawable for simple work; rastered WebP (lossless) for complex.
• iOS: PDF / SVG in asset catalog; multi-resolution rasters only for photographic content.
• Flutter: flutter_svg for vector; built-in Image.asset for raster (provide 1×/2×/3×).
• React Native: react-native-svg components; or @react-native-assets/slider-style 1×/2×/3× raster sets.

2. Theme-Aware Authoring

Illustrations must work in light and dark mode. Two strategies:

• Token-driven single source (preferred): author with CSS custom properties or currentColor placeholders that map to semantic tokens at render time.
• Paired sources: ship empty-inbox.light.svg and empty-inbox.dark.svg only when the visual language differs meaningfully.

Token-driven example:

<svg viewBox="0 0 240 160" xmlns="http://www.w3.org/2000/svg">
  <rect width="240" height="160" rx="16" fill="var(--ds-surface-subtle, currentColor)"/>
  <path d="..." fill="var(--ds-content-muted)"/>
  <path d="..." fill="var(--ds-action-primary-bg)"/>
</svg>

The build strips CSS variables and substitutes a token-typed widget per platform.

3. Tokenized Illustration Slots

Define a small alias set used by every illustration:

{
  "illustration": {
    "fg":        { "$value": "{color.content.default}" },
    "fgMuted":   { "$value": "{color.content.muted}" },
    "accent":    { "$value": "{color.action.primary.bg}" },
    "surface":   { "$value": "{color.surface.subtle}" }
  }
}

4. Compose Delivery

@Composable
fun Illustration(id: IllustrationId, modifier: Modifier = Modifier) {
    val colors = DsTheme.illustration
    val painter = when (id) {
        IllustrationId.EmptyInbox -> rememberEmptyInboxPainter(colors)
    }
    Image(painter = painter, contentDescription = null, modifier = modifier)
}

rememberEmptyInboxPainter is a generated Compose Painter from the SVG with colors wired to the theme.

5. SwiftUI Delivery

Two paths:

• Compile SVGs to PDF and drop into .xcassets with "Preserve Vector Data" enabled; use symbol image tinting for single-color illustrations.
• For multi-color illustrations, generate Shape / Path code via svg-to-swiftui and inject colors from the environment.

struct EmptyInbox: View {
    @Environment(\.dsTheme) var theme
    var body: some View {
        ZStack {
            BackgroundShape().fill(theme.illustration.surface)
            ForegroundShape().fill(theme.illustration.fg)
            AccentShape().fill(theme.illustration.accent)
        }
        .accessibilityHidden(true)
    }
}

6. Flutter Delivery

class DsIllustration extends StatelessWidget {
  const DsIllustration.emptyInbox({super.key, this.size = 240});
  final double size;

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context).extension<AppIllustration>()!;
    return SvgPicture.asset(
      'assets/illustrations/empty_inbox.svg',
      width: size,
      colorFilter: null, // use multi-color token substitution via build
      theme: SvgTheme(currentColor: theme.fg),
    );
  }
}

7. React Native Delivery

export const EmptyInbox = ({ width = 240 }: { width?: number }) => {
  const t = useTheme().illustration;
  return (
    <Svg width={width} viewBox="0 0 240 160">
      <Rect width={240} height={160} rx={16} fill={t.surface} />
      <Path d="..." fill={t.fgMuted} />
      <Path d="..." fill={t.accent} />
    </Svg>
  );
};

8. Sizing & Layout

Illustrations are aspect-ratio constrained. Components accept a width or maxWidth and preserve intrinsic ratio; never distort by fixing both axes. Provide empty-state illustrations at 240, 320, and 400 widths as tokens, not per screen.

9. Accessibility

Illustrations are decorative by default:

• Compose: contentDescription = null.
• SwiftUI: .accessibilityHidden(true).
• Flutter: ExcludeSemantics or Semantics(label: '').
• RN: accessibilityElementsHidden + importantForAccessibility="no-hide-descendants".

When an illustration carries informational meaning, provide a real label.

10. Performance

• Keep vector node count sane (< ~300). If an illustration has thousands of paths, ship WebP/PDF raster.
• Cache painters/drawables at screen lifecycle, not per-frame.
• On Android, test on a mid-tier device; VectorDrawables can be expensive.

11. Anti-Patterns

• Full-color hex embedded in SVG source.
• Separate JPEG for every illustration (large binaries, blur on scale).
• Splash screen illustrations that are not vector or not asset-catalog-backed.
• Illustrations without a dark-mode story.
• Fixed-pixel width/height attributes in the SVG source.

Checklist

• Illustrations are vector-first (SVG / VectorDrawable / PDF) with raster only as a fallback.
• Colors inside illustration source are tokens/CSS variables, never hex.
• Every illustration renders correctly in light and dark themes, verified by snapshots.
• Dedicated illustration tokens (illustration.*) exist and are the only colors consumed.
• Illustrations are accessibility-hidden unless they carry informational meaning.
• Aspect ratio is preserved by the component API; callers set one dimension.