Blazing Story Documentation

Blazing Story is a frontend workshop for Blazor designed to build UI components and pages in isolation. It is a Blazor-native clone of Storybook.

Key characteristics:

• Blazor Native: Built almost 100% using Blazor, requiring minimal JavaScript helper scripts.
• No JS Tooling Required: You do not need to manage npm, package.json, webpack, or JavaScript/TypeScript code to create a UI catalog application.
• Blazor Workflow: Allows you to build and document your UI components using standard Blazor development patterns.

Blazing Story VRT is a Visual Regression Testing (VRT) tool for Blazing Story applications. It is built on top of Playwright's toHaveScreenshot() functionality.

Key features:

• Automatic Test Generation: Every story in your running Blazing Story app is automatically converted into a single test with one screenshot.
• Shared Baselines: Baseline screenshots are synchronized through a storage service of your choice, allowing teams to share snapshots via the cloud.
• Platform Awareness: Screenshots are named using the pattern <story id>-<platform>.png, ensuring that a screenshot is only compared against a baseline captured on the same operating system (e.g., linux, win32, or darwin).

The _template.json file serves as the source of truth for all messages and is automatically generated whenever axe is built. It is compiled from the following sources:

1. The description property of each rule.
2. The help property of each rule.
3. The metadata.messages property of each check.

To update the template, you must modify the corresponding rule or check metadata files and then perform a rebuild.

Blazing Story uses a hierarchical structure to define component documentation and variants:

• [Stories("path")] attribute: Defines the navigation path for the component in the sidebar.
• <Stories TComponent="...">: The root component of the story file that specifies which target component is being explored.
• <Story Name="...">: Represents a specific state, variant, or configuration of the target component.
• <Arguments> and <Arg>: Used to define inputs for the Controls panel.
• <Template>: Defines how the component is rendered for that specific story.
• context.Args: A special object that connects user input from the Controls panel directly to the component's attributes.

Blazing Story allows you to apply layout components at three different levels of granularity:

1. Application level: Set the DefaultLayout on the BlazingStoryApp component.
2. Component level: Set the Layout attribute on the <Stories> component.
3. Story level: Set the Layout attribute on an individual <Story> component.

The BlazingStory.ToolKit/js directory serves as a phantom type-resolution stub for the TypeScript compiler. It exists to bridge the gap between how the browser resolves runtime module imports and how the TypeScript compiler resolves file system paths.

In the project, markdown-page.ts uses a relative URL to import prism.js from the BlazingStory.ToolKit project:

import { Prism } from "../../BlazingStory.ToolKit/js/prism.js";

While this relative URL works correctly in the browser (resolving relative to the importing module's URL), the TypeScript compiler fails because it attempts to find the file on the local file system at that exact relative path, where no .d.ts file exists. The stub in this directory provides a declaration file that re-exports the actual types from the correct location, allowing type checking to pass without changing the emitted JavaScript.

To use a specific cloud storage service (like Dropbox, MinIO, WebDAV, or S3-compatible storage), you must implement the storage adapter interface in scripts/snapshot-storage.ts.

Implementation Steps:

1. Open scripts/snapshot-storage.ts (provided as an empty template).
2. Implement the required members (list, download, upload, and delete) as described in the file's comments.
3. Add any necessary connection values to vrt.config.ts so the adapter can access them.

AI Agent Shortcut: If you used an AI coding agent during project creation, a storage-adapter skill was installed (in .claude/skills/ or .agents/skills/). You can simply tell the agent which service you want to use, and it will implement the adapter and update your configuration automatically.

To ensure design consistency, apply tokens to your component styles using the var() function with the defined CSS custom properties. This allows you to update the entire design system by changing the token values in a single location.

.my-button {
    background-color: var(--color-primary);
    padding: var(--space-sm) var(--space-md);
    font-family: var(--font-family);
    font-size: var(--font-size-md);
    border-radius: 4px;
}

To add support for a new language or update an existing translation for axe-core, use the grunt translate command.

• To create a new translation: Run the command with the --lang flag specifying your language code. This generates a new JSON file populated with the default English text as a baseline.
• To update an existing translation: Re-run the same command with the same language code. This synchronizes the file by adding new messages introduced in the English source and removing messages that are no longer used.

# Create a new translation for a specific language code
grant translate --lang=<langcode>

# Update an existing translation file
grant translate --lang=<langcode>