Ripplearc Core UI

A Flutter design system package with design tokens and basic components.

Package Structure

coreui/
│
├── lib/
│   ├── ripplearc_coreui.dart               # Entry point
│   └── src/
│       ├── theme/                 # Theming system and tokens
│       │   ├── color_tokens.dart
│       │   ├── typography.dart
│       │   ├── spacing.dart
│       │   └── theme_data.dart
│       │
│       └── components/            # UI components
│           ├── buttons/
│           │   └── primary_button.dart
│           ├── switches/
│           ├── text_fields/
│           └── alerts/
│
├── test/                          # Tests
│   ├── theme/
│   └── components/
│       ├── buttons/
│       │   ├── primary_button_test.dart
│       │   └── primary_button_golden.dart
│
├── showroom/                      # Demo app
│   ├── main.dart
│   └── screens/
│       └── components_screen.dart
│
├── pubspec.yaml
└── README.md

Features

Design Tokens (colors, typography, spacing)
Basic Components:
- Buttons
- More components coming soon
Comprehensive testing (Unit, Widget, and Golden tests)
Showroom app to showcase components

Getting started

Add this package to your pubspec.yaml:

dependencies:
  ripplearc_coreui:
    git:
      url: https://github.com/ripplearc/coreui.git
      ref: main

Usage

import 'package:ripplearc_coreui/ripplearc_coreui.dart';

// Use theme
MaterialApp(
  theme: CoreTheme.light(),
  darkTheme: CoreTheme.dark(),
  // ...
);

// Use components
PrimaryButton(
  label: 'Click me',
  onPressed: () {},
);

Colors & Typography Usage

Strict Rule: Do not use static constants (e.g., CoreAlertColors.red or CoreTypography.body). Static access breaks Dark Mode support.

Always access tokens through the Theme Extension so the UI adapts to the active theme.

Incorrect — bypasses the theme; won’t update in Dark Mode.

// This will fail the build
Container(
  color: AppColors.backgroundBlueLight,
  child: Text(
    'Hello',
    style: CoreTypography.bodyMedium,
  ),
);

Correct — uses BuildContext to read the current theme tokens.

// Adapts to Light/Dark mode automatically
final colors = Theme.of(context).extension<AppColorsExtension>()!;
final typography = Theme.of(context).extension<AppTypographyExtension>()!;

Container(
  color: colors.pageBackground,
  child: Text(
    'Hello',
    style: typography.bodyMedium,
  ),
);

Development

Running Tests

Golden Tests with Docker

Why Docker? Golden test screenshots vary between platforms (macOS, Linux, Windows). The Docker container matches the CI environment (Linux) to ensure consistent screenshots.

Setup

Start Docker container:
```
docker-compose up -d
```
Get container name:
```
docker container ps
```
Look for coreui-flutter-1 or similar.
Open shell in container:
```
docker exec -it coreui-flutter-1 bash
```
Note: If your container has a different name, use docker container ps to find it, or replace coreui-flutter-1 with your container name/ID.

Run golden tests inside container:

# Verify golden tests (matching CI workflow)
flutter test test/components/*
flutter test test/theme/*
flutter test test/notifications/*

# Update golden images (Only run when a visual change is intended in a specific directory)
flutter test test/components/* --update-goldens
flutter test test/theme/* --update-goldens
flutter test test/notifications/* --update-goldens

Exit container:
```
exit
```

Note: The test/ and lib/ directories are volume-mounted, so updated golden files automatically sync to your host machine. No need to copy files manually.

Rebuilding Docker Image

Rebuild the Docker image only when switching to a branch that changes underlying dependencies (for example when pubspec.yaml or pubspec.lock — or any other dependency files — differ). If those files did not change, you can skip the rebuild and just restart the containers.

# Stop container
docker-compose down

# Rebuild and restart
docker-compose up -d --build

Local Development

# Run unit and widget tests
flutter test

# Run golden tests
flutter test --update-goldens

Note: For golden tests, use Docker (see Golden Tests with Docker above) to ensure consistent screenshots across platforms.

Running the Showroom App

cd showroom
flutter run