Skip to content

ui-layout.md

Latest commit

 

History

History
382 lines (281 loc) · 8.53 KB

ui-layout.md

File metadata and controls

382 lines (281 loc) · 8.53 KB
Raw

A.R.C. CLI - Layout & Structure Guide

Overview

This document provides guidelines for creating consistent, well-structured CLI output across the A.R.C. CLI application.

Directory Structure

arc/
├── cmd/arc/                    # Application entry point
│   └── main.go
├── internal/                   # Private application code
│   ├── branding/              # Branding constants (name, tagline)
│   ├── state/                 # State management (persisted settings)
│   └── version/               # Version information
├── pkg/                        # Public reusable packages
│   ├── cli/                   # CLI commands
│   │   ├── banner.go          # Banner rendering
│   │   ├── help.go            # Help formatting
│   │   ├── root.go            # Root command
│   │   └── theme.go           # Theme management
│   └── ui/                    # User interface components
│       ├── layout/            # Layout system for structured output
│       ├── styles/            # Styling (colors, emoji, output)
│       └── themes/            # Color themes
└── docs/                       # Documentation

UI Components

1. Layout System (pkg/ui/layout/)

The layout system provides consistent, structured output rendering.

Key Components:

  • Component - Individual UI elements (title, description, content, emoji)
  • Section - Logical grouping of components
  • Layout - Container for multiple sections

Example Usage:

import "github.com/arc-framework/arc-cli/pkg/ui/layout"

// Create a layout
l := layout.NewLayout()

// Add a section with heading
section := l.AddSection("Commands", true) // true = show border

// Add items to section
section.AddItem("🚀", "deploy", "Deploy your application")
section.AddItem("📊", "status", "Check deployment status")

// Add code snippet
section.AddCodeSnippet("Example", "arc deploy --env production")

// Render
fmt.Print(l.Render())

Output:

Commands
────────

🚀 deploy
  Deploy your application

📊 status
  Check deployment status

📦 Example
   arc deploy --env production

2. Styles System (pkg/ui/styles/)

Centralized styling and output functions.

Available Styles:

  • PrimaryStyle - Main brand color (cyan)
  • SecondaryStyle - Secondary text (gray)
  • SuccessStyle - Success messages (green)
  • ErrorStyle - Error messages (red)
  • WarningStyle - Warning messages (orange)
  • InfoStyle - Info messages (purple)

Output Functions:

import "github.com/arc-framework/arc-cli/pkg/ui/styles"

styles.Success("Deployment completed!")
styles.Error("Failed to connect to server")
styles.Warn("This action will overwrite existing files")
styles.Info("Fetching latest updates...")
styles.Debug("Connection timeout: 30s")

Emoji Constants:

styles.EmojiBrand     // 🌀 Brand logo
styles.EmojiSuccess   // ✅ Successful operations
styles.EmojiError     // ❌ Errors
styles.EmojiWarning   // ⚠️  Warnings
styles.EmojiInfo      // ℹ️  Information
styles.EmojiDeploy    // 🚀 Deploy/Launch
styles.EmojiInspect   // 🔍 Inspect/Debug
styles.EmojiBox       // 📦 Resources/Containers
styles.EmojiAgent     // 🤖 AI agent output
styles.EmojiWait      // ⏳ Loading/Processing

3. Themes System (pkg/ui/themes/)

Color theme management for banner customization.

Available Themes:

  • cyan-purple (default) - Professional gradient
  • rainbow - Full spectrum
  • fire - Yellow to red
  • ocean - Cool blues
  • matrix - Green hacker style
  • character-rainbow - Character-level coloring

Usage:

import "github.com/arc-framework/arc-cli/pkg/ui/themes"

// Get all themes
allThemes := themes.Available()

// Get default theme
defaultTheme := themes.GetDefault()

// Get rainbow colors for special effects
colors := themes.Rainbow()

Layout Patterns

Pattern 1: Simple List Output

items := []string{
    "Initialize project",
    "Install dependencies",
    "Run tests",
}

output := layout.List(styles.EmojiSuccess, items)
fmt.Print(output)

Output:

✅ Initialize project
✅ Install dependencies
✅ Run tests

Pattern 2: Structured Help

title := "Deploy Command"
description := "Deploy your application to production"
commands := map[string]string{
    "arc deploy":           "Deploy with default settings",
    "arc deploy --env prod": "Deploy to production",
    "arc deploy --dry-run":  "Test deployment without changes",
}
examples := []string{
    "arc deploy --env staging",
    "arc deploy --env production --verbose",
}

help := layout.RenderHelp(title, description, commands, examples)
fmt.Print(help)

Pattern 3: Boxed Content

title := "Important Notice"
content := "Your API keys will expire in 7 days.\nPlease renew them in the dashboard."

boxed := layout.Box(title, content)
fmt.Print(boxed)

Output:

╭─────────────────────────────╮
│                             │
│  Important Notice           │
│                             │
│  Your API keys will expire  │
│  in 7 days. Please renew    │
│  them in the dashboard.     │
│                             │
╰─────────────────────────────╯

Pattern 4: Table Output

headers := []string{"Name", "Status", "Uptime"}
rows := [][]string{
    {"api-server", "running", "5d 3h"},
    {"database", "running", "12d 8h"},
    {"cache", "stopped", "0m"},
}

table := layout.Table(headers, rows)
fmt.Print(table)

Output:

Name        Status      Uptime
──────────────────────────────────────
api-server  running     5d 3h
database    running     12d 8h
cache       stopped     0m

Best Practices

1. Consistent Emoji Usage

Always use predefined emoji constants from styles package:

✅ Good:

styles.Info("Deploying application...")
fmt.Printf("%s Starting deployment\n", styles.EmojiDeploy)

❌ Bad:

fmt.Println("🚀 Starting deployment")  // Hardcoded emoji

2. Semantic Colors

Use semantic color styles based on message type:

✅ Good:

styles.Success("Build completed")
styles.Error("Connection failed")
styles.Warn("Deprecated feature")

❌ Bad:

fmt.Println(styles.PrimaryStyle.Render("Error occurred"))  // Wrong style

3. Structured Output

Use layout system for complex output:

✅ Good:

l := layout.NewLayout()
section := l.AddSection("Results", true)
section.AddItem(styles.EmojiSuccess, "Test 1", "Passed")
fmt.Print(l.Render())

❌ Bad:

fmt.Println("Results")
fmt.Println("-------")
fmt.Println("✅ Test 1: Passed")  // Manual formatting

4. Respect --no-color Flag

Always check styles.NoColor for colored output:

✅ Good:

if !styles.NoColor {
    fmt.Println(styles.SuccessStyle.Render("Success"))
} else {
    fmt.Println("Success")
}

Or use the output functions that handle this automatically:

styles.Success("Success")  // Automatically respects NoColor

Component Templates

Command Output Template

func executeCommand() error {
    styles.Info("Starting operation...")

    // Do work
    if err := doWork(); err != nil {
        styles.Error("Operation failed: %v", err)
        return err
    }

    styles.Success("Operation completed!")
    return nil
}

List Results Template

func showResults(items []Item) {
    l := layout.NewLayout()
    section := l.AddSection("Results", true)

    for _, item := range items {
        emoji := styles.EmojiSuccess
        if !item.Success {
            emoji = styles.EmojiError
        }
        section.AddItem(emoji, item.Name, item.Status)
    }

    fmt.Print(l.Render())
}

Progress Template

func showProgress(current, total int) {
    percentage := (current * 100) / total
    styles.Info("Progress: %d%% (%d/%d)", percentage, current, total)
}

Accessibility

  • Always provide text alternatives for emoji
  • Support --no-color flag for terminal compatibility
  • Use clear, descriptive text
  • Maintain proper contrast ratios
  • Test on different terminal backgrounds

Examples

See pkg/cli/theme.go for a complete example of using the layout system for theme commands.

Future Enhancements

  • Interactive prompts (Bubble Tea integration)
  • Progress bars
  • Spinner animations
  • Multi-column layouts
  • Markdown rendering