README
¶
Design export
ui/export produces the artefacts design tools and the admin gallery read
from the same composition a shell serves. Export(theme, examples, extra...)
is the content-addressed snapshot — palette, glyphs, stylesheet and every
captured example's Props, schema, slots and observed HTML — and
ExportWithLayout adds the source layout declarations. ExportTokens and
TokenExport.DTCG project the scales into the DTCG interchange format.
ProjectProps and ProjectReplacement apply a typed proposal to a capture
and return the projected snapshot; ui/source persists
an accepted one into Go. Storybook is one application's authorized
composition, which modules/admin serves at
/admin/_gallery.
Nothing here is needed to serve a page: ui/page depends on ui,
and the package gate refuses this package in its closure. Start with
tools/designexport for the command line
and go test ./ui/export for the snapshot, token and proposal contracts.
Documentation
¶
Overview ¶
Package export is the design-tooling half of ui: content-addressed snapshots of the composed components (Export, ExportWithLayout), token export in the DTCG interchange format (ExportTokens, TokenExport.DTCG), typed proposals applied to source captures (ProjectProps, ProjectReplacement), and the Storybook a shell serves so a person can browse the same composition.
It is separate from package ui because nothing here is needed to serve a page. ui owns the stylesheet and the browser assets a shell mounts; this package reads that composition and the examples in ui/components/examples and produces artefacts for design tools, the admin gallery and tests. ui/page and the shells depend on ui; only design tooling and the admin gallery depend on this package, and the ui/page and ui/screens gates in scripts/check_packages.sh refuse it in their closures.
Index ¶
- Variables
- func StorybookCSS() string
- func StorybookPage(b Storybook, path, group string, selected examples.Example, ...) (g.Node, error)
- type DTCGDiagnostic
- type DesignExport
- func Export(theme design.Pair, captures []examples.Example, extra ...ui.Extra) (DesignExport, error)
- func ExportWithLayout(theme design.Pair, captures []examples.Example, extra ...ui.Extra) (DesignExport, error)
- func ProjectProps(theme design.Pair, captures []examples.Example, proposal PropsProposal, ...) ([]examples.Example, DesignExport, error)
- func ProjectReplacement(theme design.Pair, captures []examples.Example, proposal ReplacementProposal, ...) ([]examples.Example, DesignExport, error)
- type IconExport
- type PropsProposal
- type ReplacementProposal
- type Storybook
- type ThemeExport
- type TokenExport
- type TokenMode
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrLayoutUnknown = errors.New("source layout is unknown") ErrLayoutUnsupported = errors.New("source layout contract is unsupported") )
var ErrDTCGUnsupported = errors.New("selection is not representable as DTCG 2025.10")
var ErrSourceUnsupported = errors.New("source snapshot contract is unsupported")
var ErrStaleExport = errors.New("source proposal base differs from current source export")
ErrStaleExport means the caller must obtain the current source snapshot.
Functions ¶
func StorybookCSS ¶
func StorybookCSS() string
StorybookCSS is documentation framing. Component appearances still come from Compose, Gallery and the selected application's Extra values.
func StorybookPage ¶
func StorybookPage(b Storybook, path, group string, selected examples.Example, props, mode, width string) (g.Node, error)
StorybookPage renders the index and one live example. Previews use their own document so a modal can own focus without taking over the documentation. The server validates the selected ID and applies Props before calling this.
Types ¶
type DTCGDiagnostic ¶
type DTCGDiagnostic struct {
Path []string `json:"path"`
Code string `json:"code"`
Message string `json:"message"`
Unsupported bool `json:"unsupported,omitzero"`
}
DTCGDiagnostic addresses the source identity, not an array index or encoded interchange name. Unsupported means no document can be returned. Other diagnostics describe declaration meaning retained only in source metadata.
type DesignExport ¶
type DesignExport struct {
Schema string `json:"schema"`
RequiredFeatures []string `json:"requiredFeatures,omitempty"`
Measurements []style.Measurement `json:"measurements,omitempty"`
SourceTokens *TokenExport `json:"sourceTokens,omitempty"`
SHA256 string `json:"sha256,omitempty"`
FontPolicy string `json:"fontPolicy"`
Notices string `json:"notices"`
Themes []ThemeExport `json:"themes"`
Icons []IconExport `json:"icons"`
Examples []examples.ExampleDescription `json:"examples"`
CSS string `json:"css"`
}
DesignExport is a snapshot of captured Go invocations and observed children, not a language for constructing pages. An editor adapter consumes it; the application never executes it. PropsEditable and slot support describe the Go example API, not native editor support, accessibility approval or production readiness.
func Export ¶
func Export(theme design.Pair, captures []examples.Example, extra ...ui.Extra) (DesignExport, error)
Export captures one consumer's palette, examples and stylesheet additions. Pass examples.Gallery() for Core; a product supplies its own explicitly bound examples. No registration, network access or files are involved.
Examples are sorted by stable ID without changing the caller's slice. The digest covers encoding/json's compact output with SHA256 omitted; it changes with the exported content, not timestamps or unrelated repository edits.
func ExportWithLayout ¶
func ExportWithLayout(theme design.Pair, captures []examples.Example, extra ...ui.Extra) (DesignExport, error)
ExportWithLayout opts into v2 root declarations through the existing capture and stylesheet composition path. It makes no native/editability guarantee.
func ProjectProps ¶
func ProjectProps(theme design.Pair, captures []examples.Example, proposal PropsProposal, extra ...ui.Extra) ([]examples.Example, DesignExport, error)
ProjectProps conditionally projects one edit against the caller's authoritative examples, palette and stylesheet. It renders the current export, checks the content revision, copies the affected inputs, and renders the candidate. Ownership checks cover observed source occurrences, not arbitrary HTML emitted through opaque callbacks or separate buffers. Rendering runs trusted synchronous Go constructors; arbitrary callback effects are not rolled back. Neither source files nor persistent state are saved or locked. A persistence owner must perform its own atomic revision check. Failure returns nil examples and a zero export, never an accepted partial edit.
func ProjectReplacement ¶
func ProjectReplacement(theme design.Pair, captures []examples.Example, proposal ReplacementProposal, extra ...ui.Extra) ([]examples.Example, DesignExport, error)
ProjectReplacement conditionally replaces one typed source invocation through Example.WithReplacementAt. It shares ProjectProps's revision, ownership and two-render validation boundary, with the same trust and persistence limits. The selected source must also be directly owned and observed in the base. Paths may overlap: immutable copies always read the base, not earlier writes. Self/same-content replacements are permitted and can retain the export hash. Native adapters must separately prove correspondence and edit/save fidelity.
func (DesignExport) CheckLayoutContract ¶
func (d DesignExport) CheckLayoutContract(supported ...string) error
CheckLayoutContract checks source-generated Go values against this revision's declaration contract and the caller's understood features. It neither decodes JSON nor verifies a hash, CSS equivalence, native capabilities or write authority. Unknown source is distinct from an unsupported version/feature/value. Callers must separately prove the requested projection before performing effects.
func (DesignExport) CheckSourceContract ¶
func (d DesignExport) CheckSourceContract(supported ...string) error
CheckSourceContract composes the understood v2 feature gates. Token-only captures need no layout. Earlier layout-only v2 captures retain their existing admission rules. This checks trusted Go values, not JSON decoding, SHA-256, CSS equivalence, native capabilities, physical assets or authority to write.
func (DesignExport) WithTokens ¶
func (d DesignExport) WithTokens(tokens TokenExport) (DesignExport, error)
WithTokens attaches a validated selection to an existing v1/v2 capture, advertises its required feature and hashes a detached snapshot. Selected theme identities and values must agree with the original capture. Unknown layout stays unknown; capture does not certify downstream projection support.
type IconExport ¶
type IconExport struct {
Name string `json:"name"`
SVG string `json:"svg"`
Source string `json:"source"`
License string `json:"license"`
SHA256 string `json:"sha256"`
}
IconExport carries the exact canonical vector and its attribution. SHA256 addresses the SVG bytes, not the upstream repository's unpinned contents.
type PropsProposal ¶
type PropsProposal struct {
BaseSHA256 string `json:"baseSHA256"`
Path []string `json:"path"`
Props json.RawMessage `json:"props"`
}
PropsProposal addresses one source invocation, never a native editor object. Path contains the root ID followed by definition-local child IDs. Props uses Example.WithProps's exact-case, top-level typed patch semantics.
func (*PropsProposal) UnmarshalJSON ¶
func (p *PropsProposal) UnmarshalJSON(data []byte) error
UnmarshalJSON refuses missing, repeated and unknown fields, including casing aliases. A rejected request leaves its receiver unchanged.
type ReplacementProposal ¶
type ReplacementProposal struct {
BaseSHA256 string `json:"baseSHA256"`
Path []string `json:"path"`
ReplacementPath []string `json:"replacementPath"`
}
ReplacementProposal selects two invocations from the authoritative source snapshot. Both paths contain exact root and local child IDs, never provider IDs, slot names or indexes. ReplacementPath supplies the complete replacement inputs and renderer; Path supplies the retained destination metadata. There is no implicit override preservation, conversion or cross-interface coercion.
func (*ReplacementProposal) UnmarshalJSON ¶
func (p *ReplacementProposal) UnmarshalJSON(data []byte) error
UnmarshalJSON refuses missing, repeated, unknown and casing-aliased fields. A rejected request leaves its receiver unchanged.
type Storybook ¶
type Storybook struct {
Title string
Theme design.Pair
Examples []examples.Example
Extra []ui.Extra
// Files is an optional, immutable Storybook.js build produced from Export
// of this exact composition. All files are served through gallery authorization.
Files fs.FS
}
Storybook is one application's selected design composition. The application authorizes it before passing it to a gallery or Export; this value neither knows nor discovers other tenants. Keep tenant assets in authorized application routes or embed them in the examples, never in the shell's public static tree.
type ThemeExport ¶
type ThemeExport struct {
Mode string `json:"mode"`
Name string `json:"name"`
Tokens []design.Token `json:"tokens"`
}
ThemeExport separates the CSS selector's stable mode from its display name. Font tokens are CSS fallback stacks; this export bundles no font files.
type TokenExport ¶
type TokenExport struct {
Modes []TokenMode `json:"modes,omitempty"`
Colors []design.ColorToken `json:"colors,omitempty"`
Scales []style.ScaleValue `json:"scales,omitempty"`
Shadows []style.ShadowValue `json:"shadows,omitempty"`
Easings []style.EasingValue `json:"easings,omitempty"`
Transitions []style.TransitionValue `json:"transitions,omitempty"`
Assets []design.Asset `json:"assets,omitempty"`
Faces []design.FontFace `json:"faces,omitempty"`
}
TokenExport composes existing declaration owners as read-only source data. Colors are shared declarations resolved separately in each selected mode; scales and timing keep their existing owner-local keys and explicit units. Callers may select dependency-closed subsets and supply asset metadata. This is not a registry, source-editing API, CSS equivalence or provider approval.
func ExportTokens ¶
func ExportTokens(theme design.Pair, modes ...string) (TokenExport, error)
ExportTokens projects only explicitly selected light/dark modes, in selector order, plus the existing shared colour, scale, shadow and timing owners. It captures no components, CSS, icons or font bytes and performs no I/O. Failure returns no partial output; every returned nested value is detached.
func (TokenExport) DTCG ¶
func (s TokenExport) DTCG(mode string) ([]byte, []DTCGDiagnostic, error)
DTCG projects one explicitly selected mode of a validated TokenExport into the documented DTCG 2025.10 subset. Use an empty mode only for mode-independent selections. Output is deterministic and detached; no files or registries are read or written. Any unsupported value returns nil bytes plus all projection diagnostics. Successful output embeds its diagnostics and source identities; it does not promise editable derivations, imported fonts or a round trip.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/septagon-oss/platformkit/design"
"github.com/septagon-oss/platformkit/ui/export"
)
func main() {
owned, err := export.ExportTokens(design.Default(), "light")
if err != nil {
panic(err)
}
// Select a palette/family package explicitly; no implicit filtering of scales.
selection := export.TokenExport{Modes: owned.Modes, Colors: owned.Colors}
data, diagnostics, err := selection.DTCG("light")
fmt.Println(json.Valid(data), len(diagnostics) > 0, err)
}
Output: true true <nil>
func (TokenExport) Validate ¶
func (s TokenExport) Validate() error
Validate checks selected identities, values and dependency closure without mutation. Modes must expose the same colour/font identities, but may use different values. Assets or scales alone need no mode, component or layout. Font fallback names do not assert that matching physical faces are supplied.
type TokenMode ¶
type TokenMode struct {
Mode string `json:"mode"`
Colors []design.Token `json:"colors,omitempty"`
Fonts []design.FontFamilyToken `json:"fonts,omitempty"`
}
TokenMode holds selected theme colours and ordered fallback families under their CSS identities. Other theme token kinds are outside this projection.
Source Files