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)

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.