swiftui-style-driven-components-skill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# SwiftUI Style-Driven Components Skill

Expert guidance for any AI coding tool that supports the [Agent Skills open format](https://agentskills.io/home) — building extensible SwiftUI components using Apple's style-driven architecture patterns.

Distilled from Apple's official patterns (`ButtonStyle`, `LabelStyle`, `ToggleStyle`) into actionable, concise references for agents.

## Who this is for
- Teams building reusable SwiftUI component libraries who want Apple-standard extensibility.
- Developers creating custom components that need multiple visual styles without code duplication.
- Anyone wanting to implement environment-based styling that cascades through view hierarchies.

## How to Use This Skill

### Option A: Using skills.sh (recommended)
Install this skill with a single command:
```bash
npx skills add https://github.com/ahmadbrkt/swiftui-style-driven-components-skill --skill swiftui-style-driven-components
```

For more information, visit the [skills.sh platform page](https://skills.sh/ahmadbrkt/SwiftUI-Style-Driven-Components-Skill/swiftui-style-driven-components).

Then use the skill in your AI agent, for example:  
> Use the swiftui style-driven components skill and create a Card component with style protocol support

### Option B: Claude Code Plugin

#### Personal Usage

To install this Skill for your personal use in Claude Code:

1. Add the marketplace:
   ```bash
   /plugin marketplace add ahmadbrkt/SwiftUI-Style-Driven-Components-Skill
   ```

2. Install the Skill:
   ```bash
   /plugin install swiftui-style-driven-components@swiftui-style-driven-components-skill
   ```

#### Project Configuration

To automatically provide this Skill to everyone working in a repository, configure the repository's `.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "swiftui-style-driven-components@swiftui-style-driven-components-skill": true
  },
  "extraKnownMarketplaces": {
    "swiftui-style-driven-components-skill": {
      "source": {
        "source": "github",
        "repo": "ahmadbrkt/SwiftUI-Style-Driven-Components-Skill"
      }
    }
  }
}
```

When team members open the project, Claude Code will prompt them to install the Skill.

### Option C: Manual install
1) **Clone** this repository.  
2) **Install or symlink** the `swiftui-style-driven-components/` folder following your tool's official skills installation docs (see links below).  
3) **Use your AI tool** as usual and ask it to use the "swiftui-style-driven-components" skill for component architecture tasks.

#### Where to Save Skills

Follow your tool's official documentation, here are a few popular ones:
- **Codex:** [Where to save skills](https://developers.openai.com/codex/skills/#where-to-save-skills)
- **Claude:** [Using Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#using-skills)
- **Cursor:** [Enabling Skills](https://cursor.com/docs/context/skills#enabling-skills)

**How to verify**: 

Your agent should reference the triage/playbook in `swiftui-style-driven-components/SKILL.md` and jump into the relevant reference file for your component task.

## What This Skill Offers

This skill gives your AI coding tool comprehensive SwiftUI style-driven component guidance. It can:

### Guide Your Component Architecture
- Determine when to use style protocols vs simple components
- Structure files following Apple's organizational patterns
- Implement the Protocol → Configuration → Component → Environment chain
- Design type-safe APIs with internal type erasure

### Create Style Protocols
- Define protocols with `DynamicProperty` for environment access
- Use `@ViewBuilder @MainActor` for proper UI thread safety
- Create configuration types with nested type-erased views
- Follow Apple's `ButtonStyle`, `LabelStyle` conventions exactly

### Build Extensible Components
- Write components that read styles from environment
- Create configurations internally (never exposed to initializers)
- Wrap `style.makeBody` in `AnyView` for type erasure
- Support adding new styles without modifying existing components

### Implement Environment Styling
- Use `@Entry` macro for environment keys
- Store styles as existential types (`any ComponentStyle`)
- Create view modifiers for style application
- Enable subtree styling that cascades through hierarchies

### Apply Design System Integration
- Use design tokens instead of magic numbers
- Implement spacing, typography, and color systems
- Create consistent visual language across components
- Support theming through environment values

### Write Tests & Previews
- Organize snapshot tests for all style variants
- Structure previews for different configurations
- Test accessibility with Dynamic Type support
- Verify style isolation and environment propagation

## What Makes This Skill Different

**Apple-Native Patterns**: Follows exactly how Apple builds `ButtonStyle`, `LabelStyle`, `ToggleStyle`, and other style protocols. Your components will feel native to SwiftUI developers.

**Non-Opinionated**: Focuses on the structural pattern, not visual design. Works with any design system, component library, or project architecture.

**Practical Decision Trees**: Includes clear guidance on when to use style protocols and when to skip them. Not every component needs this pattern—the skill helps you decide.

**Complete Examples**: Every pattern includes full, compilable Swift code. No pseudo-code or incomplete snippets.

**Anti-Pattern Guidance**: Shows both correct (✅) and incorrect (❌) approaches with explanations of why patterns matter.

## Skill Structure

```
swiftui-style-driven-components/
├── SKILL.md                           # Main skill file with decision trees
└── references/
    ├── component-structure.md         # File organization and naming conventions
    ├── style-protocol.md              # Protocol definition and configuration pattern
    ├── environment-keys.md            # Environment injection and usage patterns
    ├── common-patterns.md             # Convenience initializers, parameterized styles
    ├── design-system.md               # Design tokens, typography, colors
    ├── testing.md                     # Snapshot tests and test organization
    ├── previews.md                    # Preview structure and checklist
    └── accessibility.md               # Labels, identifiers, Dynamic Type
```

## Contributing

Contributions are welcome! This repository follows the [Agent Skills open format](https://agentskills.io/home), which has specific structural requirements.

**We strongly recommend using AI assistance for contributions:**
- Use the [skill-creator skill](https://github.com/anthropics/skills/tree/main/skills/skill-creator) with Claude to ensure proper formatting
- This helps maintain the Agent Skills format and ensures your contribution works correctly with AI agents

**Please read [CONTRIBUTING.md](https://github.com/ahmadbrkt/swiftui-style-driven-components-skill/blob/HEAD/CONTRIBUTING.md) for:**
- How to use the skill-creator skill for contributions
- Agent Skills format requirements
- Quality standards and best practices
- Pull request process

This skill is maintained to reflect the latest SwiftUI style-driven component best practices and will be updated as the framework evolves.

## License

This skill is open-source and available under the MIT License. See [LICENSE](https://github.com/ahmadbrkt/swiftui-style-driven-components-skill/tree/HEAD/LICENSE) for details.

SwiftUI Style-Driven Components Skill

Expert guidance for any AI coding tool that supports the Agent Skills open format — building extensible SwiftUI components using Apple's style-driven architecture patterns.

Distilled from Apple's official patterns (ButtonStyle, LabelStyle, ToggleStyle) into actionable, concise references for agents.

Who this is for

Teams building reusable SwiftUI component libraries who want Apple-standard extensibility.
Developers creating custom components that need multiple visual styles without code duplication.
Anyone wanting to implement environment-based styling that cascades through view hierarchies.

How to Use This Skill

Option A: Using skills.sh (recommended)

Install this skill with a single command:

npx skills add https://github.com/ahmadbrkt/swiftui-style-driven-components-skill --skill swiftui-style-driven-components

For more information, visit the skills.sh platform page.

Then use the skill in your AI agent, for example:

Use the swiftui style-driven components skill and create a Card component with style protocol support

Option B: Claude Code Plugin

Personal Usage

To install this Skill for your personal use in Claude Code:

Add the marketplace:

/plugin marketplace add ahmadbrkt/SwiftUI-Style-Driven-Components-Skill

Install the Skill:

/plugin install swiftui-style-driven-components@swiftui-style-driven-components-skill

Project Configuration

To automatically provide this Skill to everyone working in a repository, configure the repository's .claude/settings.json:

{
  "enabledPlugins": {
    "swiftui-style-driven-components@swiftui-style-driven-components-skill": true
  },
  "extraKnownMarketplaces": {
    "swiftui-style-driven-components-skill": {
      "source": {
        "source": "github",
        "repo": "ahmadbrkt/SwiftUI-Style-Driven-Components-Skill"
      }
    }
  }
}

When team members open the project, Claude Code will prompt them to install the Skill.

Option C: Manual install

Clone this repository.
Install or symlink the swiftui-style-driven-components/ folder following your tool's official skills installation docs (see links below).
Use your AI tool as usual and ask it to use the "swiftui-style-driven-components" skill for component architecture tasks.

Where to Save Skills

Follow your tool's official documentation, here are a few popular ones:

Codex: Where to save skills
Claude: Using Skills
Cursor: Enabling Skills

How to verify:

Your agent should reference the triage/playbook in swiftui-style-driven-components/SKILL.md and jump into the relevant reference file for your component task.

What This Skill Offers

This skill gives your AI coding tool comprehensive SwiftUI style-driven component guidance. It can:

Guide Your Component Architecture

Determine when to use style protocols vs simple components
Structure files following Apple's organizational patterns
Implement the Protocol → Configuration → Component → Environment chain
Design type-safe APIs with internal type erasure

Create Style Protocols

Define protocols with DynamicProperty for environment access
Use @ViewBuilder @MainActor for proper UI thread safety
Create configuration types with nested type-erased views
Follow Apple's ButtonStyle, LabelStyle conventions exactly

Build Extensible Components

Write components that read styles from environment
Create configurations internally (never exposed to initializers)
Wrap style.makeBody in AnyView for type erasure
Support adding new styles without modifying existing components

Implement Environment Styling

Use @Entry macro for environment keys
Store styles as existential types (any ComponentStyle)
Create view modifiers for style application
Enable subtree styling that cascades through hierarchies

Apply Design System Integration

Use design tokens instead of magic numbers
Implement spacing, typography, and color systems
Create consistent visual language across components
Support theming through environment values

Write Tests & Previews

Organize snapshot tests for all style variants
Structure previews for different configurations
Test accessibility with Dynamic Type support
Verify style isolation and environment propagation

What Makes This Skill Different

Apple-Native Patterns: Follows exactly how Apple builds ButtonStyle, LabelStyle, ToggleStyle, and other style protocols. Your components will feel native to SwiftUI developers.

Non-Opinionated: Focuses on the structural pattern, not visual design. Works with any design system, component library, or project architecture.

Practical Decision Trees: Includes clear guidance on when to use style protocols and when to skip them. Not every component needs this pattern—the skill helps you decide.

Complete Examples: Every pattern includes full, compilable Swift code. No pseudo-code or incomplete snippets.

Anti-Pattern Guidance: Shows both correct (✅) and incorrect (❌) approaches with explanations of why patterns matter.

Skill Structure

swiftui-style-driven-components/
├── SKILL.md                           # Main skill file with decision trees
└── references/
    ├── component-structure.md         # File organization and naming conventions
    ├── style-protocol.md              # Protocol definition and configuration pattern
    ├── environment-keys.md            # Environment injection and usage patterns
    ├── common-patterns.md             # Convenience initializers, parameterized styles
    ├── design-system.md               # Design tokens, typography, colors
    ├── testing.md                     # Snapshot tests and test organization
    ├── previews.md                    # Preview structure and checklist
    └── accessibility.md               # Labels, identifiers, Dynamic Type

Contributing

Contributions are welcome! This repository follows the Agent Skills open format, which has specific structural requirements.

We strongly recommend using AI assistance for contributions:

Use the skill-creator skill with Claude to ensure proper formatting
This helps maintain the Agent Skills format and ensures your contribution works correctly with AI agents

Please read CONTRIBUTING.md for:

How to use the skill-creator skill for contributions
Agent Skills format requirements
Quality standards and best practices
Pull request process

This skill is maintained to reflect the latest SwiftUI style-driven component best practices and will be updated as the framework evolves.

License

This skill is open-source and available under the MIT License. See LICENSE for details.