ShaderKit Documentation

Effects can be applied using two methods:

1. Convenience Modifiers: Many effects have direct wrappers (e.g., .foil(), .glitter()).
2. Generic Shader Modifier: Use .shader(_ effect: ShaderEffect, tilt: CGPoint? = nil, time: TimeInterval? = nil) for effects without wrappers.

Important Rules:

• Stacking Order: Effects wrap the view they are attached to. The order of modifiers determines the visual stack (chain order = stack order).
• Layering: You can attach effects to specific sub-views to create a 'split-layer' effect where only certain parts of the card are shaded.
• Manual Context: If you are using shaders outside of a HolographicCardContainer, you must manually inject context using .shaderContext(tilt:time:touchPosition:).

CardContent()
  .foil(intensity: 0.8)
  .glitter()
  .lightSweep()

The most critical design choice is whether to attach the effect modifier chain to the entire card or just a background sub-layer. This determines how the subject interacts with the shaders.

Attach to the Whole Card

• Behavior: The foil/pattern shimmers over the subject as well.
• Best for: Opaque photos and abstract cards (e.g., PsychicHoloView, GradientFoilView).
• Warning: High-intensity patterns with 'hotspots' (like .starburst() or .galaxyHolo()) can 'burn through' the subject if applied to the whole card.

Attach to the Background Sub-layer Only

• Behavior: The subject stays pristine/clean while the foil shimmers around/behind it.
• Best for: Transparent subjects (cutout PNGs). This makes the subject look like a solid object sitting in a holographic well.
• Example: Foil+Glitter+Sweep technique.

If you are migrating from or comparing with simeydotme/pokemon-cards-css, ShaderKit uses a procedural Metal implementation. The following mapping describes how CSS signals translate to ShaderKit signals:

When generating a trading card, use the following mapping to translate user description hints into specific holographic vibes (recipes). This mapping determines the palette, effect stack, and shadowColor used in the HolographicCardContainer.

To use the holographic trading card library, add the ShaderCards product to your target and import ShaderCards.

Common Views:

• TradingCardView(card:width:): An interactive holographic card that reacts to tilt.
• CardGalleryView(): A browsable grid of the entire library.
• CardFaceView(card:width:): A static, non-shader version of a card for lists or thumbnails.

import ShaderCards

// An interactive holographic card from the library
TradingCardView(.creature(CardLibrary.emberfox), width: 300)

// The whole library in a browsable grid
NavigationStack { CardGalleryView() }

// A static face for lists and thumbnails
CardFaceView(card: .creature(CardLibrary.tidecaller), width: 160)

ShaderKit's foil effects are implemented as Metal shaders. In Xcode 26+, the Metal Toolchain is a separate download. If your build fails with the error cannot execute tool 'metal' due to missing Metal Toolchain, you must install it using the following command:

xcodebuild -downloadComponent MetalToolchain

Important: Shaders only compile correctly through Xcode's build system. Do not use swift build or swift run, as these methods copy .metal files raw, which results in all foils rendering blank. Always build using xcodebuild (or the ShaderKitDemo scheme when working within the repository).

To create interactive holographic cards in SwiftUI, wrap your content in a HolographicCardContainer and chain shader effects like .foil(), .glitter(), or .lightSweep() onto the content. The container automatically handles device motion tracking (gyroscope), drag gestures for manual tilt, 3D rotation, dynamic shadows, and shader context injection.

import ShaderKit

HolographicCardContainer(width: 260, height: 380) {
    CardContent()
        .foil()
        .glitter()
        .lightSweep()
}

The trading-card skill transforms an image into a holographic, Pokémon-style trading card using ShaderKit primitives. The skill is designed to be zero-interview: it takes an image and automatically invents a creature name, stats (HP, Role, Motto), and signature skills.

Invocation Pattern

/trading-card <image-path> [optional short description hint]

• <image-path> (required): The path to the source image. A transparent-PNG cutout is recommended so the subject floats over the foil, though opaque photos are supported (they will receive a tint scrim).
• description hint (optional): A few words to steer the design (e.g., "icy", "cosmic", "gold legendary", "cyberpunk"). If omitted, a design is chosen at random.

/trading-card ~/dog.png "cosmic vibe"

ShaderCards allows you to render holographic trading cards in SwiftUI using procedural artwork and real-time Metal foil effects. You can display cards from the built-in library, build custom cards using CardBuilder, or provide an interactive design interface via CardStudioView.

import ShaderCards

TradingCardView(.creature(CardLibrary.emberfox), width: 300)