alter 3.0.0

A lightweight, mobile-first Flutter design system featuring curated Geist typography, semantic tokens, and modular UI components.

Alter

A lightweight, mobile-first design system built for Flutter applications, featuring curated Geist typography, semantic tokens, and modular UI components.

---

🚀 Getting Started

1. Add Dependency

Add alter to your pubspec.yaml:

dependencies:
  alter: ^2.0.1

2. Import Alter

Import the single barrel file into your Dart code:

import 'package:alter/alter.dart';

3. App-Level Theme Setup

Set fontFamily: AlterTypography.geistFont in your main MaterialApp theme:

MaterialApp(
  theme: ThemeData(
    fontFamily: AlterTypography.geistFont,
    scaffoldBackgroundColor: AlterSemanticTokens.baseWhite,
  ),
  home: const HomeScreen(),
);

---

🎨 Styles & Tokens Architecture

Alter organizes design tokens into foundational layers:

• AlterColors: 234 raw color palette swatches extracted from Figma design variables.
• AlterSemanticTokens: Semantic color mappings (baseWhite, baseGray, interactivePrimary, textPrimary, stroke100, statusSuccess, etc.).
• AlterTypography: Text style scale tokens (display, displayXl, h1Serif, h1Bold, h2, h3, bodyLgBold, body, caption, etc.).

---

🧩 Components Catalog

Inputs (lib/components/inputs/)

• InputControl: Configurable surface primitive with multiline bounds safety, leading/trailing slots, hover/focus rings, and error message container.
• TextInput: Full FormField<String> wrapper with TextInputMode filters, deferred isRequired validation on blur, and direct keyboardType fallback override.
• TextAreaInput: Multiline text area supporting both fixed reserved lines (lines: 4) and dynamic adaptive height (minLines: 1) that expands as users type.
• NumericInput: Live comma grouping (International and Indian systems), decimal precision limits, bounds validation (minValue/maxValue), and trailing action slot.
• CurrencyInput: Financial currency entry preset with Euro default icon, 2-decimal precision, and prefix formatting.
• PasswordInput: Secure input with interactive eye visibility toggle, built-in space denial, character limits, and strength validation rules.
• SearchInput: Search entry field with leading search icon, auto-clearing close button, and search keyboard action.
• OTPInput: Multi-box pin verification control with digit filtering, auto-focus forwarding, and backspace navigation.

Buttons (lib/components/buttons/)

• ButtonText: Text buttons with ButtonType (gray, white, primary, red) and ButtonSize (normal, large).
• ButtonIcon: Square icon buttons (48x48, 64x64) with selection state and accent colors.
• ButtonIconGhost: Borderless ghost icon buttons with gesture hooks (onTap, onLongPress).
• ButtonGraphicText: Dual-label badge button (customizable title & subtitle).
• ButtonGraphicImage: Compact icon button container.

Selects & Toggles (lib/components/selects/)

• Checkbox: Tri-state selection control supporting unchecked, intermediate, and checked states.
• Radio: Single-selection control with token-driven active/inactive states.
• Switch: Smooth animated toggle switch with Alter semantic color fills.
• ToggleIcon: Outlined/filled Material-style icon toggle with color fallback.
• ToggleText: Text-based segmented/tabbed toggle button with animated sliding indicator.

Pills & Badges (lib/components/pills/)

• Pill: Status badge & filter pill with animated cross-fades across default and compact sizes.
• AdvancedPill: Multi-segment status tag with customizable leading/trailing slots and interactive press states.
• Badge: Count badge and status dot indicator with multiple color variants and auto-overflow formatting (99+).

Status & Feedback (lib/components/status/)

• Toast: Floating banner notification component with success, warning, danger, and info semantic variants.
• FeedbackText: Inline form helper and error message caption with semantic iconography.

Mobile Navigation, Tabs & Header (lib/mobile/, lib/components/tabs/)

• ApplicationHeaderMobile: Top mobile navigation header with title, subtitle, return button, composite action buttons, and animated child slot.
• Tabs: Horizontal segment/navigation control composed of TabItem sub-components with icon and label support.
• TabItem: Atomic tab button supporting label, leading icon, and active states.
• AlterBottomNavigationBar: Floating pill bottom navigation bar with responsive tab items.
• BottomNavigationBarAction: Bottom navigation bar composed with primary/secondary action triggers.
• BottomNavigationButton: Primary call-to-action button embedded in bottom navigation.
• BottomNavigationItem: Individual clickable item within the bottom navigation bar.

Utilities (lib/components/utilities/)

• Avatar: Compact user and entity avatar supporting image and placeholder icon variants.
• CarouselControl: Carousel navigation overlay control bar providing chevron previous/next triggers.
• Divider: 1px content divider line supporting horizontal and vertical orientations.
• ListItem: Universal list tile with title, subtitle, leading action slot, and dual trailing slots.

---

🚧 Upcoming in v3.0.0 (In Development)

Note

The components and modules below are currently in active development on the main branch to bring responsive Web and Sites support to Alter. They will be officially published to pub.dev in the upcoming v3.0.0 release.

Web Header & Desktop Navigation (lib/web/application_header/)

• ApplicationHeader: Responsive web & desktop application header supporting title, navigation pages, actions, and profile avatar slots.
• ApplicationHeaderButtonIcon: 48x48 action button for headers supporting icon glyphs and embedded user avatars.
• ApplicationHeaderButtonText: 48px height text action button/badge for headers.

Foundations (lib/foundations/)

• AlterDeviceScope: Inherited device mode (AlterDevice.pc / AlterDevice.mobile) propagation scope ensuring child components synchronize layout with parent grid/marker state without individual viewport queries.

Multimedia Presentation (lib/components/utilities/)

• AlterMediaView: Universal media presentation widget supporting static images, animated GIFs, and muted looping autoplay videos with viewport-aware play/pause automation.

Sites & Responsive Blocks (lib/sites/)

• BiographyBlock: Responsive entity and biography card with logo, title, badges, and bio description.
• BrandBlock: Responsive social proof and partner brand showcase block.
• FooterBlock: Responsive footer block with contact email, copy-to-clipboard action, and social profile links.
• GraphicsBlock: Responsive project and portfolio card molecule supporting single & multi-item carousels for images, animated GIFs, and viewport-aware autoplay videos.
• GraphicsCarouselBlock: Responsive full-width horizontal carousel block for visual showcases.
• GraphicsGridBlock: Responsive project grid layout (PC 2-column, Mobile 1-column) consuming GraphicsBlock cards with device scope synchronization.
• HeaderBlock: Responsive section header block with expandable divider line and bold title.
• HeroBlock: Responsive hero banner section block with avatar, display typography headline, subtitle, and action buttons for landing pages.
• HeroProjectsBlock: Responsive project case study hero block with logo, title, metadata grid, notice banner, tech stack, and action links.
• MobileMockupBlock: Responsive mobile screen showcase and entity card (428:926 iPhone container) supporting images, GIFs, and viewport-aware autoplay looping videos with BiographyBlock.
• MobileMockupsGridBlock: Responsive mobile screen showcase grid & carousel with unified BiographyBlock entity metadata supporting image and video lists with viewport autoplay.

---

📖 Live Interactive Documentation (Widgetbook)

Check out the interactive catalog and workbench in the example/ directory:

cd example
flutter run -d chrome

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.