Asset Pipeline

Asset Pipeline now covers two related jobs for Crystal applications:

  1. a production web asset compiler for import maps, JavaScript, styles, images, fonts, and other application-owned files
  2. a native UI and host-integration layer for Apple platforms, with HIG-driven validation for macOS and iOS
  3. a web-first design-system proof with semantic tokens, opinionated components, motion helpers, font handling, and screenshot validation

The native track is no longer hypothetical. As of April 17, 2026, the Apple validation ledger reports:

Installation

Add the shard to your shard.yml:

dependencies:
  asset_pipeline:
    github: amberframework/asset_pipeline
    version: 0.37.0

Then run:

shards install

What This Repo Does Now

Native Apple UI

The shard includes a large native-first UI surface with AppKit and UIKit renderers, host bridges, and validation studies for the Apple Human Interface Guidelines.

Current native work includes:

Legacy FrontLoader Asset Pipeline

The original FrontLoader flow is still here for import maps and web assets. That part of the shard remains useful, but it is no longer the whole story.

Application Static Assets

Amber V2 applications author files under app/assets/ and compile them into public/assets/. Every emitted file is named from its SHA-256 content digest, including images, fonts, documents, WebAssembly, and other static files. CSS and JavaScript references to local dependencies are rewritten to the compiled URLs, and compressible files receive deterministic .gz siblings.

require "asset_pipeline"

compiler = AssetPipeline::StaticAssets::Compiler.new(
  source_root: "app/assets",
  output_root: "public/assets",
  public_path: "/assets"
)

manifest = compiler.build
puts manifest.path("images/logo.svg")
puts manifest.integrity("stylesheets/app.css")

The manifest is written last, so a failed build cannot replace the last valid release contract. Use compiler.check (or AssetPipeline::StaticAssets::Compiler.check(output_root: "public/assets")) in deployment validation to detect missing, modified, or incorrectly precompressed output. Only files named by the prior manifest are pruned; unrelated files beneath public/ are not deleted.

Web Design System

A vanilla-JS, token-driven design system that ships from the same Crystal shard as the native renderers. No Node, no bundler, no Stimulus for canonical helpers. Components render to strings; CSS variables drive light/dark themes; motion, charts, and form flows are first-party SVG and JavaScript.

The current proof includes reusable Crystal wrappers for command palette, schedule heatmap, payment/auth forms, theme switching, fields, pricing cards, tabs, carousel, dialog, and timeline patterns. Chrome DevTools audits cover keyboard behavior, sampled contrast, reduced motion, accessibility names, state captures, axe-core, IBM Equal Access, and a light/dark screenshot matrix.

Agents start here, in order:

Reference:

Native Apple Example

Here is the shape of the newer export-oriented API surface:

shortcuts = UI::AppShortcuts.new(
  "Asset Pipeline",
  bundle_identifier: "com.example.asset-pipeline"
)

shortcuts.add_shortcut("Open Inbox") do |shortcut|
  shortcut.add_phrase("Open my inbox")
  shortcut.add_parameter("section", prompt: "Which section?", type: "string")
end

widgets = UI::Widgets.new("Asset Pipeline")
widgets.add_widget("Daily Summary", identifier: "daily-summary")

notifications = UI::NotificationsCatalog.new("Asset Pipeline")
notifications.add_category("exports") do |category|
  category.add_action("open", "Open Export", options: ["foreground"])
end

puts shortcuts.export_app_intents_scaffold
puts widgets.export_widgetkit_scaffold
puts notifications.export_swift_scaffold

Where To Look

Apple Validation Workflow

The Apple work is validated with paired macOS and iOS studies against HIG reference imagery. The validation artifacts live under:

.claude/skills/apple-platform-guide/validation/

That folder contains:

For a browser-friendly stable path, open:

Legacy FrontLoader Notes

For existing web-only users of Asset Pipeline:

Start with:

Status

The Apple-native work is finally at the point where the repo should be treated as a real native UI and host-integration project, not just an experiment with screenshots. The remaining work is mostly around deeper platform packaging and contributor ergonomics, not whether the core surface exists.