flutter_artist_styles

The core styling system for the FlutterArtist ecosystem. This package provides an enterprise-grade, strict architectural solution for Design Token Management without incurring circular dependency issues.

⚠️ Pre-release Teaser (v0.9.0):
This version exclusively unveils the underlying architecture and capabilities of faColors (The Core Color Token Graph).
The advanced automated orchestration engine faTheme remains under active polish and will be officially introduced in the upcoming major v1.0.0 release.

---

🎨 Interactive Previews

Core Action Token Mechanics

Discover how token graphs fluidly map interactions without static context breaks.

---

Automatic Token Code Generation

The official FlutterArtist Code Generator rendering full cross-theme translation graphs instantly.

---

🚀 Key Architectural Concepts (faColors)

Rather than relying on brittle, floating Color variables, faColors builds a structured Color Graph directly into the Flutter infrastructure through a localized BuildContext graph extension (context.faColors).

Core Principles

• Strict Component Mapping
  Sub-divided into semantic layout namespaces:

  • ink
  • action
  • surface
  • input
  • divider

• Zero Circular Dependencies
  Separates the visual execution layer from high-level widgets, enabling components to remain uncoupled from hardcoded color instances.

• Safe Pairings Enforcement
  Built-in pairing guarantees between active surface backgrounds (fill) and content typography/icons (ink).

---

🛠 Basic Structural Rules

When constructing dynamic action structures (such as custom Buttons, Chips, or Interactive Overlays), strictly enforce the following context layouts:

1. Creating Interactive Elements

• Always map target components through:

  context.faColors.action.xxx
  

2. Standard Color Group Pairing

• Solid backgrounds using:

  context.faColors.action.fill.primary
  

• Must exclusively pair text/icons with:

  context.faColors.action.ink.onPrimaryFill
  

3. Reverse Color Group Pairing

• Outlined or secondary layouts using:

  context.faColors.action.fill.reversePrimary
  

• Must always map content text/icons with:

  context.faColors.action.ink.primary
  

4. Action Borders & Outlines

• Define boundaries via:

  context.faColors.action.stroke.xxx
  

---

📖 Complete Usage Examples

Here are two complete production-grade examples demonstrating how to properly map tokens to prevent layout decoupling.

---

Example 1: Standard Elevated Action Button

Perfect for core primary application touchpoints, ensuring proper contrast parameters.

import 'package:flutter/material.dart';
import 'package:flutter_artist_styles/flutter_artist_styles.dart';

class FaPrimaryButton extends StatelessWidget {
  final String text;
  final VoidCallback onPressed;

  const FaPrimaryButton({
    super.key,
    required this.text,
    required this.onPressed,
  });

  @override
  Widget build(BuildContext context) {
    // Standard pairing:
    // fill.primary paired with ink.onPrimaryFill
    final backgroundColor =
        context.faColors.action.fill.primary;

    final contentColor =
        context.faColors.action.ink.onPrimaryFill;

    return GestureDetector(
      onTap: onPressed,
      child: Container(
        padding: const EdgeInsets.symmetric(
          horizontal: 24.0,
          vertical: 12.0,
        ),
        decoration: BoxDecoration(
          color: backgroundColor,
          borderRadius: BorderRadius.circular(8.0),
          boxShadow: [
            BoxShadow(
              color: context.faColors.common.black
                  .withValues(alpha: 0.05),
              blurRadius: 4,
              offset: const Offset(0, 2),
            ),
          ],
        ),
        child: Text(
          text,
          style: TextStyle(
            color: contentColor,
            fontWeight: FontWeight.bold,
            fontSize: 16.0,
          ),
        ),
      ),
    );
  }
}