Proposal: YAZA UI Design System

Status: Accepted product direction — initial web starter foundation implemented; full system remains incomplete
Scope: A YAZA-owned design language, component standard, web renderer, and future mobile renderer
Decision: YAZA UI is the intended default UI system for projects generated by YAZA. An initial YAZA-authored web token stylesheet and static example now ship in yaza new --web; the compiler-integrated package, renderers, and mobile target do not exist yet.

1. Purpose

YAZA needs a user-interface system that belongs to its language and toolchain. YAZA UI should make it straightforward to build accessible, responsive websites and, when YAZA's mobile compiler targets are available, mobile applications from the same design contract.

YAZA UI will be an original implementation and visual identity. Material UI, Bootstrap, Apple Human Interface Guidelines, Android guidance, and web standards can be studied as references for user expectations and interoperability. Their source code, component implementations, or distinctive visual systems are not to be copied or repackaged as YAZA UI.

The ambition is to make YAZA UI a compelling global choice for frontend work. No proposal can guarantee market leadership; that depends on the quality of the shipped system, its accessibility, performance, documentation, ecosystem, and developer adoption.

Why build with the YAZA ecosystem

YAZA UI is intended to work as one part of a connected product stack: the YAZA language and compiler, CLI, web runtime, data modules, design tokens, project templates, and future mobile targets. The intended advantages are:

• Less integration work: one project manifest, CLI, diagnostics, test flow, and version policy should reduce the number of separate tools developers must configure and keep compatible.
• Safer connections between layers: shared YAZA types and generated contracts should reduce duplicate request models and hand-written conversions between UI, API, and data layers.
• A faster development loop: project generation, local component documentation, typed properties, and compiler checks should shorten the path from a new project to a working screen.
• Consistent visual quality: shared tokens and component states should keep spacing, typography, contrast, responsive behavior, and interaction feedback coherent across pages and supported targets, while still allowing product-specific themes.
• Measured runtime efficiency: the renderers should include only used components and styles, avoid hidden runtime dependencies, and minimize avoidable serialization and rendering work. Native and web targets must be measured independently; a shared design contract alone does not make them fast.

These are product goals, not current performance results. Before claiming that YAZA is faster or more efficient than another stack, compare equivalent applications and report build time, shipped code and style size, startup time, interaction latency, memory use, accessibility results, and developer setup time. Keep the measurements reproducible and publish the tested target, hardware, and configuration.

2. Product decisions

1. YAZA UI is the default. Future yaza new --web projects install and use the supported YAZA UI version by default. A generated project must not silently fall back to another UI framework.
2. One design contract, target-specific renderers. Tokens, component names, states, and layout intent are shared. The web renderer emits semantic HTML/CSS; future iOS and Android renderers map the contract to native platform controls where that improves accessibility or platform behavior. Pixel-identical rendering is not required across targets.
3. The design system is YAZA-owned. YAZA owns the component specifications, implementations, token set, examples, tests, and compatibility policy. Standards and interoperability formats remain welcome; third-party component implementations are not runtime dependencies.
4. Accessibility is part of each component's contract. Components ship with documented semantics, names, keyboard and touch behavior, focus states, contrast requirements, and assistive-technology expectations.
5. Responsive behavior is intrinsic. Layouts adapt to available space, content, input mode, text scaling, and safe areas. Breakpoints describe layout needs, not specific phone models.
6. The generated project is useful immediately. The web starter includes the YAZA UI theme, responsive application shell, navigation, page layout, form example, loading/error/empty states, and a small example page. A mobile starter follows after native build targets are available.

3. YAZA visual identity

YAZA UI needs a recognizable visual language without making every application look like the same template. The initial direction is YAZA Current: clear structure, confident typography, compact signal accents, layered surfaces, and motion that explains state changes rather than decorating them.

The YAZA mark's branching Y can inspire alignment and state transitions: a line or surface may branch to indicate navigation, a selected path, or a progressive workflow. It should not be stamped onto every control. A restrained base palette, semantic status colors, typography scale, spacing rhythm, surface elevations, corner shapes, icon grid, and motion curves become named tokens. Individual brands can override theme tokens while preserving readable contrast and consistent behavior.

The palette and exact geometry remain design proposals until reviewed against real web and mobile screens. YAZA UI must not depend on one color, shadow, gradient, font, or animation to communicate meaning.

4. Standards from the smallest unit upward

Every UI artifact must have a versioned specification entry. The registry is the authoritative source for names, tokens, component behavior, platform mappings, and examples.

For every primitive and component, the registry records: purpose; YAZA API; semantic HTML or native role; required and optional properties; visual tokens; all states; keyboard and pointer behavior; responsive rules; text scaling and localization behavior; accessibility requirements; security considerations; test fixtures; and supported renderer versions.

5. Responsive, web, and mobile behavior

The web system starts with content that works in a narrow viewport and expands as space becomes available. It uses flexible sizing and intrinsic CSS layout, with named container and viewport thresholds only where a layout genuinely changes. Components should wrap, reflow, scroll, or switch presentation according to their documented contract. They must not require a fixed device width.

The web renderer should prefer native semantic elements and browser behavior. It adds ARIA only when native HTML cannot express the needed state. It supports keyboard operation, visible focus, screen readers, zoom, reduced motion, high contrast preferences, right-to-left text, and user-selected text size. Touch targets and safe-area insets are accounted for on mobile web.

The mobile renderer should honor platform safe areas, orientation and window resizing, system text scaling, platform navigation, and native accessibility APIs. Shared YAZA UI declarations may choose an appropriate platform presentation; they should not force a web-shaped control onto a native app when it conflicts with expected platform behavior. A shared contract does not remove the need for separate iOS and Android adapters or compiler targets.

Proposed mobile engine: YAZA Frame Engine

The proposed engine name is YAZA Frame Engine (YFE). Its rendering core, layout rules, state invalidation, animation scheduler, display-list generation, and diagnostics are authored and maintained as YAZA technology. Minimal platform adapters may call Metal, Vulkan/OpenGL ES, display-vsync, native text shaping/input, lifecycle, and accessibility APIs. The engine does not embed Flutter, Skia, Compose, React Native, or another UI renderer. OS GPU drivers and native accessibility/input services remain platform facilities.

The architecture is designed to keep application code and ordinary state updates on a native ahead-of-time path. It has no JavaScript VM or JSON message bridge in the rendering path. The current YAZA compiler emits C for its native macOS target and has no iOS or Android target, GPU backend, or mobile host adapter; all of the mobile design below is future work.

Frame pipeline

1. Compile a YAZA Frame IR (YFIR). The compiler lowers UI declarations into a typed semantic scene graph. Static structure, component properties, event handlers, accessibility roles, and stable node identifiers are recorded at build time. Unused components and shader variants should be removed from a target build.
2. Generate a phase dependency map. Each state read is associated with the smallest affected phase and node: structure, measurement, placement, paint, or accessibility. The compiler emits direct update paths for stable node identifiers, avoiding a whole-tree runtime comparison for every change. A paint-only value such as opacity should not trigger layout; a size change must invalidate its dependent layout subtree.
3. Publish immutable frame snapshots. Application and asynchronous I/O work update typed state away from the render commit. The frame boundary receives a consistent snapshot; it does not block on network, disk, or database work. The memory model and safe cross-thread publication must be specified before this can be implemented.
4. Schedule by the display deadline. YFE integrates with YAZA's planned scheduler and the OS vsync clock. Input and accessibility state changes take priority, then required layout and paint work; prefetching, image preparation, and nonessential effects run only when budget remains. At 120 Hz the frame interval is about 8.33 ms; at 60 Hz it is about 16.67 ms. The profiler reports when each stage misses its target instead of hiding the missed frame.
5. Build a retained display list. The renderer keeps stable geometry, glyph/image resources, and GPU command data across frames, updates only dirty ranges, and batches compatible draw work. Per-frame scratch storage uses bounded ring buffers whose reuse waits for the corresponding GPU completion fence. Virtual lists create only the visible window plus a bounded prefetch region.
6. Submit through a YAZA-owned GPU backend. YFE generates its own rendering commands and shader set, then submits them through Metal on Apple platforms or Vulkan with an OpenGL ES fallback where Android device support requires it. Shader source and variants are built ahead of time where the target permits; driver-specific pipeline creation and caching still need device testing and must not block the first interactive frame.
7. Keep semantics connected to pixels. The scene graph also produces the native accessibility tree. VoiceOver/TalkBack, system text shaping, IME composition, selection, and platform lifecycle use narrow OS adapters. Custom drawing must never make a control disappear from the platform accessibility system.

Candidate YAZA differentiator

The ambitious research direction is compiler-generated phase dependency maps coupled to a frame-deadline scheduler. The compiler would know which state can affect structure, geometry, paint, or accessibility and produce direct invalidation routes; the runtime would schedule only the affected work against the display's next frame deadline. This aims to combine static YAZA type information, retained rendering, and asynchronous task scheduling in one design.

Individual techniques already exist in current systems: Flutter Impeller precompiles shader pipelines and supports distributing frame work across threads; Jetpack Compose tracks composition/layout/draw phases and can skip unnecessary phases; React Native Fabric has a shared native renderer core and JSI interoperability; SwiftUI provides tools to identify view-update hitches. YAZA's proposed distinction is the compiler-generated phase map integrated with its own typed UI contract and scheduler, not a claim that phase skipping, ahead-of-time shaders, native rendering, or a shared renderer are new by themselves. Prior-art review and benchmark evidence are required before describing this as novel or first-of-its-kind.

Performance and quality gates

YFE must be measured on named iOS and Android devices at supported refresh rates using the same screens, data, assets, and interaction scripts as comparison frameworks. Report cold start and first interactive frame, p50/p95/p99 frame time, missed-vsync rate, input-to-display latency, CPU/GPU time, memory and steady-state allocations, battery/thermal behavior, app size, and accessibility results. A release profile should require bounded memory, no YAZA-owned allocation in a warmed steady-state animation/scroll path, and at least 99% of frames within the display interval for the documented baseline workloads. Performance should degrade gracefully on lower refresh rates, thermal pressure, or weaker GPUs without postponing input or accessibility updates.

The exact baseline device set and pass thresholds must be published before cross-framework speed claims. Test initial launch separately from warmed runs; exercise long lists, text input, navigation, animation, image loading, rotation/window resize, background/foreground, and low-memory conditions. A faster average does not pass if tail latency, dropped frames, accessibility, power use, or application size regresses materially.

Delivery order and constraints

1. Specify YFIR, state dependency rules, frame ownership, UI-thread rules, and a deterministic CPU reference renderer.
2. Implement the frame planner and profile tools in YAZA, then verify partial invalidation and frame-buffer lifetime with adversarial tests.
3. Following RFC 0008, prototype a thin Android arm64-v8a host first (with x86_64 emulator coverage), then add an iOS arm64 host after the binding generator and ABI review are repeatable. Each host supplies lifecycle, GPU surface, vsync, text input, and accessibility APIs through a narrow reviewed boundary.
4. Add YAZA-owned Metal and Vulkan/OpenGL ES render backends, ahead-of-time component/shader selection, and GPU-fence-aware buffer reuse.
5. Add native text/input controls, scrolling/virtualization, accessibility, responsive layout, and the cross-device benchmark suite.

The engine cannot meet its goals without the accepted ownership/concurrency work, native target compiler, mobile installers, GPU resource lifetime rules, and platform conformance. It must be implemented incrementally; this proposal does not claim a working mobile app or a performance advantage today.

6. Proposed developer experience

The exact YAZA syntax will be specified with the component API before implementation. The intended feel is typed and concise:

ui.page(title: "Catalog"):
    ui.stack(gap: "space.4"):
        ui.heading(level: 1, text: "Products")
        ui.button(label: "Add product", intent: primary, on_press: add_product)

This is illustrative syntax, not currently valid YAZA code. Component properties should expose semantic intent (intent, size, disabled, busy, label) and tokens rather than require users to memorize framework-specific utility class combinations.

The future CLI should provide:

• yaza ui docs for the local component reference and examples;
• yaza ui check for token, component-property, accessibility-contract, and unsupported-target diagnostics;
• yaza ui theme to create and validate theme tokens;
• project generation that pins a compatible YAZA UI version and records it in the YAZA manifest.

The CLI names are proposals until the package and command grammar are implemented.

7. Quality and release gates

YAZA UI must not claim a component is ready merely because it renders once. A release-ready component needs:

• a reviewed specification and stable typed API;
• keyboard, pointer, touch, assistive-technology, and responsive behavior tests appropriate to the component;
• WCAG 2.2 AA checks for contrast, keyboard access, focus visibility, resize, and target sizing where applicable;
• visual regression fixtures at narrow, medium, wide, zoomed, right-to-left, reduced-motion, and high-contrast settings;
• long text, localization, loading, disabled, error, and empty-state coverage;
• web performance measurements including shipped CSS/JS size and interaction responsiveness;
• a documented deprecation and migration policy for API or token changes.

The baseline is WCAG 2.2 Level AA, with stronger focus visibility and touch usability where practical. Passing automated checks alone is not proof of accessibility; manual keyboard and screen-reader review is required for interactive patterns.

8. Staged delivery

1. Design foundations: identity review, token schema, color/contrast validation, typography, spacing, geometry, motion, responsive layout rules, and component registry.
2. Web primitives: semantic rendering, layout primitives, theme provider, focus treatment, and browser test harness.
3. Core components: text and links, buttons, form controls, alerts, cards, navigation, dialogs, tables, and loading/error/empty states.
4. Generated web default: yaza new --web produces a runnable project whose primary UI is YAZA UI, with examples and local docs.
5. Patterns and templates: commerce, CRUD, dashboard, content, and form patterns, with accessibility and responsive review.
6. Mobile contract and renderers: only after YAZA has a working iOS and Android compilation/build path; add platform adapters and verify native behaviors separately.

9. Interoperability references

• Use WCAG 2.2 as the web accessibility baseline.
• Use the WAI-ARIA Authoring Practices Guide to specify keyboard and semantic behavior for custom web widgets, while preferring native HTML controls where available.
• Use the Design Tokens Format Module as an interchange option. It is a W3C Community Group report, not a W3C Recommendation or the sole source of YAZA UI's token semantics.
• Study responsive layout principles in Bootstrap's grid documentation as a public reference, without copying Bootstrap's code or naming system.
• Review Apple layout guidance and Android adaptive-layout guidance when designing platform renderers.
• Compare renderer architecture using Flutter Impeller, Jetpack Compose phases, React Native Fabric, and Apple's SwiftUI performance guidance. These are references for prior-art analysis and measurements, not implementation dependencies.

10. Current state

The web template now includes the initial YAZA UI web foundation v0.1: YAZA-owned CSS custom-property tokens, an original responsive starter page, and styles for layout, navigation, buttons, cards, badges, alerts, text/select/textarea/date inputs, checkbox, section-link navigation, table, native disclosure, progress, loading skeleton, and empty state. The example uses semantic HTML and native browser behavior where available. The stylesheet has no third-party framework dependency and includes light/dark color preference, visible focus, and reduced-motion handling.

The current templates/web example is a responsive dashboard and component showcase using YAZA-authored CSS tokens, semantic HTML, 27 inline SVG/CSS chart patterns, page-local JavaScript, and a generated YAZA glass icon atlas. Its sample interactions include theme switching, chart-range display changes, chart search, custom chart-card width and height, project search/filter/pagination, an in-memory create-project dialog, CSV download, dismissible notices, and toast feedback. Chart and control motion uses short spring-like transitions and respects reduced-motion preferences. This is a template demonstration, not a UI package or compiler-integrated component system: the JavaScript is not YAZA, chart data is static, sample data resets on reload, and no API or database is connected. A YAZA UI DSL, browser renderer, reusable package API, token validation pipeline, visual regression suite, production accessibility audit, and Android/iOS renderer are still absent. The mobile design remains a proposal and YAZA has no mobile build target. The data/media proposal does not imply those capabilities already exist. Implementation status is tracked in the runtime capability matrix and must be updated only when code and release evidence exist.

← Kembali ke semua dokumentasiVersi dan status rilis →