diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index c779fa396..ff56891d6 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -321,6 +321,20 @@ "category": "Development & Workflow", "description": "Three-phase Requirements → Design → Tasks workflow for Claude Code and Codex — EARS notation acceptance criteria, autonomous execution loop, cross-spec dependencies, and post-implementation acceptance testing." }, + { + "name": "stark", + "displayName": "Stark", + "source": { + "source": "local", + "path": "./plugins/f0d010c/stark" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development & Workflow", + "description": "UI/UX design plugin for AI coding agents with product-flow routing, platform-native interface guidance, asset planning, and shipped-reference analysis before code." + }, { "name": "tailtest", "displayName": "tailtest", diff --git a/README.md b/README.md index 568a2ca22..c0c347a70 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,7 @@ Third-party plugins built by the community. [PRs welcome](#contributing)! - [Registry Broker](https://github.com/hashgraph-online/registry-broker-codex-plugin) - Delegate tasks to specialist AI agents via the HOL Registry, plan, find, summon, and recover sessions. - [Session Orchestrator](https://github.com/Kanevry/session-orchestrator) - Session orchestration for Claude Code, Codex, and Cursor IDE — structured planning, wave-based execution, VCS integration (GitLab + GitHub), quality gates, and clean session close-out with issue tracking. - [Spec-Driven Development](https://github.com/Habib0x0/spec-driven-plugin) - Three-phase Requirements → Design → Tasks workflow for Claude Code and Codex — EARS notation acceptance criteria, autonomous execution loop, cross-spec dependencies, and post-implementation acceptance testing. +- [Stark](https://github.com/f0d010c/stark) - UI/UX design plugin for AI coding agents with product-flow routing, platform-native interface guidance, asset planning, and shipped-reference analysis before code. - [tailtest](https://github.com/avansaber/tailtest-codex) - Hook-powered test generation -- detects files changed during an agent turn and instructs Codex to write and run tests automatically. Zero config, 8 languages. - [Tartiner Labs](https://github.com/tartinerlabs/skills) - Agent skills for git workflows, GitHub automation, security audits, code refactoring, and project tooling. - [Team Skills Platform](https://github.com/Colin4k1024/tsp) - Role-based team delivery framework — Tech Lead-orchestrated 8-role system with 195+ skills, 27 specialist agents, 80+ commands, hooks, and ECC harness for Claude Code, Codex, and OpenCode. diff --git a/plugins.json b/plugins.json index 1edf4d908..8cfdb1942 100644 --- a/plugins.json +++ b/plugins.json @@ -3,7 +3,7 @@ "name": "awesome-codex-plugins", "version": "1.0.0", "last_updated": "2026-05-13", - "total": 68, + "total": 69, "categories": [ "Development & Workflow", "Tools & Integrations" @@ -229,6 +229,16 @@ "source": "awesome-codex-plugins", "install_url": "https://raw.githubusercontent.com/Habib0x0/spec-driven-plugin/HEAD/.codex-plugin/plugin.json" }, + { + "name": "Stark", + "url": "https://github.com/f0d010c/stark", + "owner": "f0d010c", + "repo": "stark", + "description": "UI/UX design plugin for AI coding agents with product-flow routing, platform-native interface guidance, asset planning, and shipped-reference analysis before code.", + "category": "Development & Workflow", + "source": "awesome-codex-plugins", + "install_url": "https://raw.githubusercontent.com/f0d010c/stark/HEAD/.codex-plugin/plugin.json" + }, { "name": "tailtest", "url": "https://github.com/avansaber/tailtest-codex", diff --git a/plugins/f0d010c/stark/.codex-plugin/plugin.json b/plugins/f0d010c/stark/.codex-plugin/plugin.json new file mode 100644 index 000000000..771388312 --- /dev/null +++ b/plugins/f0d010c/stark/.codex-plugin/plugin.json @@ -0,0 +1,57 @@ +{ + "name": "stark", + "version": "0.6.3", + "description": "UI/UX design plugin for AI coding agents. Routes product flows, web, Windows, Apple, Android, cross-platform, and token requests to focused design skills before code.", + "author": { + "name": "stark contributors", + "url": "https://github.com/f0d010c/stark" + }, + "homepage": "https://github.com/f0d010c/stark", + "repository": "https://github.com/f0d010c/stark", + "license": "Apache-2.0", + "keywords": [ + "codex", + "design", + "ui", + "ux", + "frontend", + "swiftui", + "winui", + "compose", + "tauri", + "electron", + "tailwind", + "anti-slop" + ], + "skills": "./skills/", + "include": [ + "./agents/", + "./assets/", + "./commands/", + "./docs/review-contract.md", + "./references/", + "./scripts/detect_platform.py", + "./scripts/token_export.py" + ], + "interface": { + "displayName": "stark", + "shortDescription": "Multi-platform UI/UX design skills for AI coding agents.", + "longDescription": "stark helps AI coding agents design from product flow, platform, native/cross-platform track, assets, and reference analysis before generating code. It includes UX, web, Windows, Apple, Android, cross-platform design, design-token skills, references, commands, and helper scripts.", + "developerName": "stark contributors", + "category": "Development & Workflow", + "capabilities": [ + "Design", + "UX", + "Code Generation", + "Audit", + "Reference" + ], + "websiteURL": "https://github.com/f0d010c/stark", + "defaultPrompt": [ + "Design a non-generic landing page.", + "Improve the onboarding UX for this app.", + "Audit this UI for AI slop." + ], + "brandColor": "#111111" + } +} diff --git a/plugins/f0d010c/stark/LICENSE b/plugins/f0d010c/stark/LICENSE new file mode 100644 index 000000000..bf0c7dbdc --- /dev/null +++ b/plugins/f0d010c/stark/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for describing the origin of the Work and + reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Support. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or support. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 stark contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing permissions + and limitations under the License. diff --git a/plugins/f0d010c/stark/README.md b/plugins/f0d010c/stark/README.md new file mode 100644 index 000000000..8651587c0 --- /dev/null +++ b/plugins/f0d010c/stark/README.md @@ -0,0 +1,258 @@ +# stark + +[![Release](https://img.shields.io/github/v/release/f0d010c/stark?style=for-the-badge&label=release&labelColor=111111&color=ff6b4a)](https://github.com/f0d010c/stark/releases) +[![License](https://img.shields.io/badge/license-Apache--2.0-8b5cf6?style=for-the-badge&labelColor=111111)](LICENSE) +[![Platforms](https://img.shields.io/badge/platforms-Web%20%7C%20Windows%20%7C%20Apple%20%7C%20Android-14b8a6?style=for-the-badge&labelColor=111111)](README.md) +[![Made for Agents](https://img.shields.io/badge/made%20for-AI%20coding%20agents-0ea5e9?style=for-the-badge&labelColor=111111)](README.md) + +UI/UX design plugin for AI coding agents. +It routes UI and UX requests to focused skills, asks the right product-flow / platform / track / direction questions first, then helps agents ship usable interfaces instead of template clones. + +Stark keeps compatibility notes for multiple agent environments, while Codex installs use the Codex manifest and shared skill folders. + +## Why this exists + +AI design output often defaults to the same web-shaped answer: React, Tailwind, shadcn, Inter, purple gradients, centered hero, three cards, CTA strip. +That is wrong for native apps, and it is boring on the web. + +`stark` pushes Codex toward the right product and design idiom before code: + +- UX maps product flows, states, IA, forms, onboarding, dashboards, and repeated-use ergonomics before pixels. +- UX produces a compact decision brief that platform skills must preserve during implementation. +- Contextual UX briefs cover agent runs, operational dashboards, activation onboarding, checkout/upgrade, and editor/canvas tools. +- UI produces a visual decision brief for surface type, hierarchy, density, component grammar, motion budget, and state visuals. +- Product quality checks force specific jobs, proof surfaces, complete states, scan speed, and one memorable anchor before code. +- Creative direction turns "make it creative" into a concrete world, metaphor, material language, repeated motif, forbidden defaults, and one tasteful risk. +- Interaction guidance chooses CSS, Motion, GSAP, native scroll CSS, Lenis, command palettes, split panes, timelines, or no motion by surface and product job. +- Web implementation tracks choose static HTML/CSS/JS, Vite + React, Next, Astro, or the existing stack by interaction needs and dependency risk. +- Cinematic landing guidance separates key art from page design, then defines typography, art direction, section rhythm, and motion choreography before code. +- Asset planning chooses icons, screenshots, references, typography, generated UI mocks, and optional GPT/Codex image generation before implementation. +- Reference analysis extracts structure from shipped products, Mobbin/Figma screens, docs, and screenshots without copying visual identity. +- Web asks for an aesthetic direction first. +- Windows asks whether the app should be system-like WinUI, branded WinUI, Tauri, or Electron. +- Apple asks whether the app should be strict SwiftUI, branded SwiftUI, React Native, Flutter, or desktop web shell. +- Android asks whether the app should be Compose, branded Compose, React Native, Flutter, or Compose Multiplatform. +- Cross-platform work gets explicit fidelity warnings. +- Token work uses W3C DTCG design tokens and export scripts. + +## Install In Codex + +Use this repository as a Codex plugin source. +In this source repo, the Codex manifest lives at: + +```text +.codex-plugin/plugin.json +``` + +For local testing, point Codex at this folder or install it through the Codex plugin flow once it is pushed to a GitHub repository. +After installation, restart or reload Codex so the skills are indexed. +Marketplace mirrors may place the same manifest under their bundled plugin folder, such as `plugins/f0d010c/stark/.codex-plugin/plugin.json`. + +## Use + +Use natural language. +Codex should trigger the matching skill automatically: + +```text +Design a landing page for a type foundry that does not look like generic SaaS. +Make a Win11 app shell with NavigationView and Mica. +Build an iOS 26 settings screen with Liquid Glass. +Create a Compose Material 3 Expressive workout screen. +Improve the onboarding UX for this app so users reach first value faster. +Design the empty, loading, error, and success states for this dashboard. +Translate this iOS settings screen into a Windows app. +Audit this React hero section for UX problems and AI design slop. +Export these DTCG tokens to Tailwind and SwiftUI. +``` + +If the target is ambiguous, `design-router` asks which platform to use instead of defaulting to web. + +## Slash Command Mapping + +The Claude version included slash commands. +Codex uses skills and natural-language routing instead. + +| Claude command | Codex equivalent | +|---|---| +| `/stark ux ` | `Use stark ux-design for ` or ask for UX / product flow help | +| `/stark web ` | `Use stark web-design for ` or simply ask for a web UI | +| `/stark windows ` | Ask for a Windows / WinUI / Fluent UI | +| `/stark apple ` | Ask for an iOS / macOS / SwiftUI UI | +| `/stark android ` | Ask for Android UI; Stark should ask which Android track to use | +| `/stark auto ` | Ask normally; `design-router` decides or asks one question | +| `/stark-audit ` | `Audit with stark for UX problems and AI design slop` | +| `/stark-assets ` | `Use stark assets to plan the visual assets before building` | +| `/stark-reference ` | `Use stark reference analysis before designing from shipped examples` | +| `/stark-translate apple windows ` | `Translate this Apple UI to Windows using stark` | + +## What's Inside + +```text +stark/ + .codex-plugin/plugin.json Codex plugin manifest + skills/ + design-router/ UX and platform dispatcher + ux-design/ flows, states, IA, forms, onboarding, dashboards + references/ui-patterns/ surface taxonomy, creative direction, implementation tracks, visual hierarchy, responsive containment, asset selection, reference analysis, motion budget, interaction techniques, cinematic landing system, UI audit rubric, product quality bar + references/ux-patterns/ contextual product-flow briefs + web-design/ 6 web aesthetic directions + windows-design/ WinUI / branded WinUI / Tauri / Electron + apple-design/ SwiftUI / RN / Flutter / desktop shells + android-design/ Compose / RN / Flutter / CMP + cross-platform-design/ idiom translation and fidelity warnings + design-tokens/ DTCG token generation and export + references/ design philosophy, platform docs, web patterns + assets/ token bundles, font pairs, screenshot gallery + scripts/ platform detection and token export helpers + commands/ legacy Claude slash-command docs +``` + +## Web Directions + +`web-design` asks for one direction before generating code: + +1. Editorial Swiss revival +2. Tactile brutalism +3. Type-as-hero +4. Glow + grain +5. Industrial monospace +6. Active bento + +Each direction has its own typography, palette, layout grammar, motion language, copy voice, reference apps, and ban list. + +## Product Quality Bar + +For "make this better" work, Stark now pushes agents to answer five practical questions before code: + +- What specific job does this surface serve? +- What proof does the UI show instead of only claiming value? +- Which empty/loading/error/permission/success states exist? +- How fast can a returning user scan status, owner, risk, and next action? +- What is the one memorable visual anchor? + +That keeps generated output closer to a real product and farther from generic demo furniture. + +## Interaction Decisions + +Stark includes product-facing motion and interaction guidance: + +- CSS transitions for simple hover/focus/disclosure feedback. +- Motion for React when component state, layout continuity, sheets, modals, or route/detail transitions matter. +- GSAP ScrollTrigger only for complex timeline or pinned storytelling. +- Native scroll-driven CSS for lightweight progress and reveal effects. +- Lenis only when scroll feel is part of a brand/editorial surface. +- No animation when stability, reading, copying, comparing, or recovery matters more. + +The interaction brief also makes agents state the motion budget, reduced-motion behavior, and rejected techniques. + +Stark explicitly knows about Motion/motion.dev. It should choose Motion for React component state, layout continuity, sheets, modals, command palettes, and route/detail transitions. It should choose GSAP only for complex timeline or pinned-scroll storytelling, and CSS/native APIs for simpler interactions. + +## Cinematic Landing Pages + +For launch pages, editorial scroll stories, immersive brand pages, and campaign-style websites, Stark treats the hero image as only one part of the system. + +The agent should define: + +- key art: one dominant object, scene, product proof, or specimen that carries the first viewport +- page system: typography, palette, layout rhythm, recurring motif, and section sequence +- choreography: reveal order, pinned moments, parallax depth, gallery transitions, and reduced-motion behavior +- restraint: fewer sections, fewer type choices, no unrelated card grids, and no motion added to hide weak composition + +This is the difference between a good-looking hero screenshot and a page that stays coherent after the first scroll. + +## Creative Direction + +For high-craft work, Stark asks agents to define a world before code: + +- visual metaphor +- material language +- typography personality +- layout grammar +- motion voice +- repeated motif +- forbidden defaults +- one tasteful risk +- restraints that keep the risk coherent + +This pushes agents away from random decoration and toward a specific art direction that can survive across the full page or app. + +## Web Implementation Tracks + +React is supported as a first-class path, especially for stateful, componentized, animated, or app-like web surfaces. + +Stark still asks whether React is actually needed: + +- static HTML/CSS/JS for simple pages and lightweight effects +- Vite + React for advanced interactive sites, product demos, dashboards, command palettes, inspectors, and reusable components +- Next for app/marketing hybrids, SEO, routing, server data, and auth +- Astro for content-heavy or editorial sites with islands of interactivity + +The stack brief includes dependency risk notes so agents do not add npm packages just for decoration, especially during active supply-chain incidents. + +## Screenshot Gallery + +The repo keeps proof as screenshots instead of full generated app folders, so the plugin stays small and installable. + +| Project | Desktop | Mobile | +|---|---|---| +| Operator Console | Operator Console desktop screenshot | Operator Console mobile screenshot | +| BuildDesk | BuildDesk desktop screenshot | BuildDesk mobile screenshot | +| Artifact Labs | Artifact Labs desktop screenshot | Artifact Labs mobile screenshot | +| Ops Dashboard | Ops Dashboard desktop screenshot | Ops Dashboard mobile screenshot | +| CRM v2 | CRM v2 desktop screenshot | CRM v2 mobile screenshot | + +Screenshot folders live under `assets/screenshots//`. + +## Native Tracks + +`stark` does not silently turn every app into a website. + +- Windows: system-like WinUI 3, branded WinUI 3, Tauri 2, Electron +- Apple: strict SwiftUI, branded SwiftUI, React Native, Flutter, Tauri / Electron for macOS +- Android: Compose strict, branded Compose, React Native, Flutter, Compose Multiplatform +- Cross-platform: Tauri, React Native, Flutter, Compose Multiplatform, Uno, Avalonia, MAUI with explicit tradeoffs + +## Helper Scripts + +```bash +python scripts/detect_platform.py --text "Build a Settings screen for Win11 with Mica" +python scripts/token_export.py --input assets/tokens/fluent-2.json --target winui --output Resources.xaml +``` + +## Review Contract + +Stark keeps a small tested helper-script surface. Runtime bundle scope, local-only files, token-export guarantees, and change policy are documented in `docs/review-contract.md`. + +## Test + +Run SkillForge against the plugin: + +```bash +npx agent-skillforge lint . --format text +npx agent-skillforge smoke . +python -m unittest discover -s tests +``` + +These commands use `npx`; no repo-local package install is required. + +Manual smoke prompts: + +```text +Design a developer-tool landing page in the industrial monospace direction. +Improve the trial onboarding UX for a B2B analytics dashboard. +Audit src/components/Hero.tsx for UX and web anti-slop issues. +Translate this Apple settings screen to Windows using stark. +``` + +## Compatibility + +This repo is intentionally multi-agent shaped: + +- Codex reads `.codex-plugin/plugin.json` and `skills/*/SKILL.md`. +- Other agent environments can reuse the same skill text and command notes from source. + +The skill content is shared so fixes improve both surfaces. + +## License + +Apache 2.0. See `LICENSE` and `NOTICE`. diff --git a/plugins/f0d010c/stark/SECURITY.md b/plugins/f0d010c/stark/SECURITY.md new file mode 100644 index 000000000..52f0efdd4 --- /dev/null +++ b/plugins/f0d010c/stark/SECURITY.md @@ -0,0 +1,25 @@ +# Security Policy + +## Scope + +`stark` is a documentation + reference plugin. It does not execute untrusted code or accept user data. The primary attack surface is the `scripts/` directory, which contains small Python helper utilities for platform detection and token export. + +## Supported versions + +The latest tagged release is supported. Earlier versions are not maintained. + +## Reporting a vulnerability + +If you find a security issue: + +1. Do **not** open a public issue. +2. Open a private security advisory via GitHub: https://github.com/f0d010c/stark/security/advisories/new +3. Include reproduction steps and impact assessment. + +You should expect an initial response within 14 days. + +## Out of scope + +- Vulnerabilities in third-party dependencies (file with the dependency upstream) +- Issues in user-generated output (the plugin guides design choices; it does not validate generated code for security) +- Issues in local visual QA projects that are not part of this repository diff --git a/plugins/f0d010c/stark/agents/openai.yaml b/plugins/f0d010c/stark/agents/openai.yaml new file mode 100644 index 000000000..175b02ce4 --- /dev/null +++ b/plugins/f0d010c/stark/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Stark" + short_description: "Opinionated UI/UX design routing for agents" + default_prompt: "Use Stark to design, improve, or audit this UI/UX so it feels specific, usable, and ready for real product work." + +policy: + allow_implicit_invocation: true diff --git a/plugins/f0d010c/stark/assets/font-pairs.md b/plugins/f0d010c/stark/assets/font-pairs.md new file mode 100644 index 000000000..4b0065d1c --- /dev/null +++ b/plugins/f0d010c/stark/assets/font-pairs.md @@ -0,0 +1,66 @@ +# Font Pairings — Quick Reference + +## Web (paid licenses) + +| # | Display | Body | Mono | Source | +|---|---|---|---|---| +| 1 | PP Editorial New | PP Neue Montreal | PP Neue Montreal Mono | Pangram Pangram | +| 2 | PP Editorial Old | PP Formula | PP Formula Mono | Pangram Pangram | +| 3 | Söhne | Tiempos Text | Söhne Mono | Klim | +| 4 | GT Sectra | GT America | GT America Mono | Grilli Type | +| 5 | ABC Diatype | ABC Diatype | ABC Diatype Mono | Dinamo | +| 6 | New Edge 666 | Söhne | Söhne Mono | Newglyph + Klim | +| 7 | Reckless Neue | Söhne | Söhne Mono | Displaay + Klim | +| 8 | Authentic Sans | Authentic Sans | Authentic Mono | abcdinamo | + +## Web (free / Google Fonts) + +| # | Display | Body | Mono | +|---|---|---|---| +| 1 | Bricolage Grotesque | Inter Tight | JetBrains Mono | +| 2 | Fraunces (variable) | Inter Tight | JetBrains Mono | +| 3 | Instrument Serif | Geist | Geist Mono | +| 4 | Newsreader | Geist | Geist Mono | +| 5 | Boldonse | Manrope | Geist Mono | + +## Apple (system) + +| Surface | Font | +|---|---| +| Default UI | SF Pro (Display + Text auto-switch) | +| Rounded contexts | SF Pro Rounded | +| Code / monospace | SF Mono | +| Editorial / serif | New York | + +Never SF Pro replaced by web fonts. Use `.font(.body)` etc., not `.font(.system(size: 17))`. + +## Windows (system) + +| Surface | Font | +|---|---| +| All UI | Segoe UI Variable (axes: wght 100–700, opsz) | +| Code | Cascadia Mono / Cascadia Code | +| Iconography | Segoe Fluent Icons | + +Never Segoe UI plain — that's the legacy face. + +## Android (system + brand) + +| Surface | Font | +|---|---| +| Default body | Roboto Flex (variable) | +| Brand display | Per-app — but stay within M3E weight/size scale | +| Code | Roboto Mono / JetBrains Mono | +| Iconography | Material Symbols (variable axes: wght/fill/grade/opsz) | + +## Banned across all platforms + +- Inter (most common AI default) +- Space Grotesk (second most common) +- Roboto on iOS (use SF Pro) +- SF Pro on Android (use Roboto Flex) +- Segoe UI on web (it's Windows system; web has no equivalent reason to use it) +- Default Tailwind font stack untouched +- FontAwesome on Apple (use SF Symbols) +- FontAwesome on Android (use Material Symbols) +- FontAwesome on Windows (use Segoe Fluent Icons) diff --git a/plugins/f0d010c/stark/assets/screenshots/artifact-labs-site/desktop.png b/plugins/f0d010c/stark/assets/screenshots/artifact-labs-site/desktop.png new file mode 100644 index 000000000..18aa06354 Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/artifact-labs-site/desktop.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/artifact-labs-site/mobile.png b/plugins/f0d010c/stark/assets/screenshots/artifact-labs-site/mobile.png new file mode 100644 index 000000000..9c43009e1 Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/artifact-labs-site/mobile.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/builddesk/desktop.png b/plugins/f0d010c/stark/assets/screenshots/builddesk/desktop.png new file mode 100644 index 000000000..a4a84f95e Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/builddesk/desktop.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/builddesk/mobile.png b/plugins/f0d010c/stark/assets/screenshots/builddesk/mobile.png new file mode 100644 index 000000000..f985e2074 Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/builddesk/mobile.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/crm-v2/desktop.png b/plugins/f0d010c/stark/assets/screenshots/crm-v2/desktop.png new file mode 100644 index 000000000..22f9ac955 Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/crm-v2/desktop.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/crm-v2/mobile.png b/plugins/f0d010c/stark/assets/screenshots/crm-v2/mobile.png new file mode 100644 index 000000000..3a064ff94 Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/crm-v2/mobile.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/operator-console/desktop.png b/plugins/f0d010c/stark/assets/screenshots/operator-console/desktop.png new file mode 100644 index 000000000..abffcda9f Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/operator-console/desktop.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/operator-console/mobile.png b/plugins/f0d010c/stark/assets/screenshots/operator-console/mobile.png new file mode 100644 index 000000000..e69a57f6a Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/operator-console/mobile.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/ops-dashboard/desktop.png b/plugins/f0d010c/stark/assets/screenshots/ops-dashboard/desktop.png new file mode 100644 index 000000000..d888fc12a Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/ops-dashboard/desktop.png differ diff --git a/plugins/f0d010c/stark/assets/screenshots/ops-dashboard/mobile.png b/plugins/f0d010c/stark/assets/screenshots/ops-dashboard/mobile.png new file mode 100644 index 000000000..3449dfd70 Binary files /dev/null and b/plugins/f0d010c/stark/assets/screenshots/ops-dashboard/mobile.png differ diff --git a/plugins/f0d010c/stark/assets/tokens/apple-system.json b/plugins/f0d010c/stark/assets/tokens/apple-system.json new file mode 100644 index 000000000..4e8ba4627 --- /dev/null +++ b/plugins/f0d010c/stark/assets/tokens/apple-system.json @@ -0,0 +1,84 @@ +{ + "$description": "Apple system color and typography reference (iOS 26 / macOS 26 Tahoe). Maps to SwiftUI Color extension via scripts/token_export.py. Liquid Glass treated as a material, not a color.", + "color": { + "label": { + "primary": { "$value": "Color(.label)", "$type": "color", "$description": "System primary label, adapts light/dark/high-contrast" }, + "secondary": { "$value": "Color(.secondaryLabel)","$type": "color" }, + "tertiary": { "$value": "Color(.tertiaryLabel)","$type": "color" }, + "quaternary":{ "$value": "Color(.quaternaryLabel)","$type": "color" } + }, + "background": { + "primary": { "$value": "Color(.systemBackground)", "$type": "color" }, + "secondary": { "$value": "Color(.secondarySystemBackground)", "$type": "color" }, + "tertiary": { "$value": "Color(.tertiarySystemBackground)", "$type": "color" }, + "grouped": { "$value": "Color(.systemGroupedBackground)", "$type": "color" } + }, + "fill": { + "primary": { "$value": "Color(.systemFill)", "$type": "color" }, + "secondary": { "$value": "Color(.secondarySystemFill)", "$type": "color" } + }, + "system": { + "red": { "$value": "Color(.systemRed)", "$type": "color" }, + "orange": { "$value": "Color(.systemOrange)", "$type": "color" }, + "yellow": { "$value": "Color(.systemYellow)", "$type": "color" }, + "green": { "$value": "Color(.systemGreen)", "$type": "color" }, + "mint": { "$value": "Color(.systemMint)", "$type": "color" }, + "teal": { "$value": "Color(.systemTeal)", "$type": "color" }, + "cyan": { "$value": "Color(.systemCyan)", "$type": "color" }, + "blue": { "$value": "Color(.systemBlue)", "$type": "color" }, + "indigo": { "$value": "Color(.systemIndigo)", "$type": "color" }, + "purple": { "$value": "Color(.systemPurple)", "$type": "color" }, + "pink": { "$value": "Color(.systemPink)", "$type": "color" }, + "brown": { "$value": "Color(.systemBrown)", "$type": "color" } + }, + "tint": { + "$description": "App accent. Define ONE accent in asset catalog; reference via .tint(.accentColor)", + "accent": { "$value": "Color.accentColor", "$type": "color" } + } + }, + "typography": { + "$description": "SwiftUI Font.TextStyle — never hard-coded points. Sizes adapt with Dynamic Type.", + "large-title": { "$value": "Font.largeTitle", "$type": "string", "$description": "34pt regular" }, + "title": { "$value": "Font.title", "$type": "string", "$description": "28pt regular" }, + "title-2": { "$value": "Font.title2", "$type": "string", "$description": "22pt regular" }, + "title-3": { "$value": "Font.title3", "$type": "string", "$description": "20pt regular" }, + "headline": { "$value": "Font.headline", "$type": "string", "$description": "17pt semibold" }, + "body": { "$value": "Font.body", "$type": "string", "$description": "17pt regular" }, + "callout": { "$value": "Font.callout", "$type": "string" }, + "subheadline": { "$value": "Font.subheadline","$type": "string" }, + "footnote": { "$value": "Font.footnote", "$type": "string" }, + "caption": { "$value": "Font.caption", "$type": "string" }, + "caption-2": { "$value": "Font.caption2", "$type": "string" } + }, + "spacing": { + "$description": "8pt grid (half-step 4pt). Prefer .padding() default (which encodes the grid).", + "xxs": { "$value": "4", "$type": "dimension" }, + "xs": { "$value": "8", "$type": "dimension" }, + "s": { "$value": "12", "$type": "dimension" }, + "m": { "$value": "16", "$type": "dimension" }, + "l": { "$value": "24", "$type": "dimension" }, + "xl": { "$value": "32", "$type": "dimension" }, + "xxl": { "$value": "48", "$type": "dimension" } + }, + "material": { + "$description": "iOS/macOS materials. Liquid Glass via .glassEffect() is separate.", + "ultra-thin": { "$value": ".ultraThinMaterial", "$type": "string" }, + "thin": { "$value": ".thinMaterial", "$type": "string" }, + "regular": { "$value": ".regularMaterial", "$type": "string", "$description": "Default sidebar/toolbar" }, + "thick": { "$value": ".thickMaterial", "$type": "string" }, + "ultra-thick": { "$value": ".ultraThickMaterial", "$type": "string" } + }, + "liquid-glass": { + "$description": "iOS 26+ Liquid Glass. Apply via .glassEffect() / GlassEffectContainer / .buttonStyle(.glass).", + "default": { "$value": ".glassEffect()", "$type": "string" }, + "container": { "$value": "GlassEffectContainer { ... }", "$type": "string" }, + "button-style": { "$value": ".buttonStyle(.glass)", "$type": "string" }, + "scroll-edge": { "$value": ".scrollEdgeEffectStyle(.soft)", "$type": "string" } + }, + "motion": { + "$description": "Spring physics ONLY for UI motion. Linear/easeIn/easeOut banned.", + "spring": { "$value": ".spring(response: 0.4, dampingFraction: 0.85)", "$type": "string" }, + "spring-snappy": { "$value": ".spring(response: 0.25, dampingFraction: 0.9)", "$type": "string" }, + "spring-bouncy": { "$value": ".spring(response: 0.5, dampingFraction: 0.65)", "$type": "string" } + } +} diff --git a/plugins/f0d010c/stark/assets/tokens/awwwards-brutalist.json b/plugins/f0d010c/stark/assets/tokens/awwwards-brutalist.json new file mode 100644 index 000000000..e7fe45264 --- /dev/null +++ b/plugins/f0d010c/stark/assets/tokens/awwwards-brutalist.json @@ -0,0 +1,44 @@ +{ + "$description": "Bespoke 'Tactile Brutalist' direction — example token bundle. Visible grid lines, harsh type, color clashes.", + "color": { + "ink": { "$value": "#000000", "$type": "color", "$description": "Brutalist allows pure black — context-dependent" }, + "paper": { "$value": "#F0F0EB", "$type": "color" }, + "rule": { "$value": "#000000", "$type": "color" }, + "accent": { "$value": "#FF3B00", "$type": "color", "$description": "Aggressive orange — clash intentional" }, + "warn": { "$value": "#FFE600", "$type": "color", "$description": "Hi-vis yellow accent" }, + "muted": { "$value": "#888888", "$type": "color" } + }, + "typography": { + "$description": "Mono-driven brutalist — Söhne Mono / Neue Haas Grotesk Mono", + "display": { "$value": { "fontFamily": "Söhne Mono", "fontSize": "clamp(40px, 7vw, 96px)", "fontWeight": 700, "lineHeight": 0.95, "letterSpacing": "-0.04em", "textTransform": "uppercase" }, "$type": "typography" }, + "headline": { "$value": { "fontFamily": "Neue Haas Grotesk Display", "fontSize": "clamp(28px, 4vw, 56px)", "fontWeight": 700, "lineHeight": 1.0, "letterSpacing": "-0.02em" }, "$type": "typography" }, + "body": { "$value": { "fontFamily": "Neue Haas Grotesk Text", "fontSize": "16px", "fontWeight": 400, "lineHeight": 1.45 }, "$type": "typography" }, + "mono": { "$value": { "fontFamily": "Söhne Mono", "fontSize": "13px", "fontWeight": 400, "lineHeight": 1.4 }, "$type": "typography" } + }, + "spacing": { + "$description": "Strict 8px grid — visible, not hidden", + "0": { "$value": "0", "$type": "dimension" }, + "1": { "$value": "8px", "$type": "dimension" }, + "2": { "$value": "16px", "$type": "dimension" }, + "3": { "$value": "24px", "$type": "dimension" }, + "4": { "$value": "32px", "$type": "dimension" }, + "8": { "$value": "64px", "$type": "dimension" }, + "16": { "$value": "128px","$type": "dimension" } + }, + "radius": { + "none": { "$value": "0", "$type": "dimension", "$description": "Brutalist = sharp corners" } + }, + "border": { + "thin": { "$value": "1px solid #000", "$type": "string" }, + "thick": { "$value": "2px solid #000", "$type": "string" }, + "very-thick": { "$value": "4px solid #000", "$type": "string", "$description": "For hero blocks" } + }, + "motion": { + "$description": "Snappy, mechanical — no soft springs", + "snap": { "$value": "cubic-bezier(0.85, 0, 0.15, 1) 200ms", "$type": "string" } + }, + "grain": { + "$description": "Visible grain texture — tactility is the point", + "opacity": { "$value": "0.08", "$type": "number" } + } +} diff --git a/plugins/f0d010c/stark/assets/tokens/awwwards-editorial.json b/plugins/f0d010c/stark/assets/tokens/awwwards-editorial.json new file mode 100644 index 000000000..64cf42e5d --- /dev/null +++ b/plugins/f0d010c/stark/assets/tokens/awwwards-editorial.json @@ -0,0 +1,47 @@ +{ + "$description": "Bespoke 'Editorial Swiss Revival' direction — example token bundle for a distinctive web project. Use as a starting point, not a copy.", + "color": { + "ink": { "$value": "#0A0908", "$type": "color", "$description": "Near-black with warmth — never pure #000" }, + "paper": { "$value": "#FAF8F3", "$type": "color", "$description": "Warm off-white — never pure #FFF" }, + "rule": { "$value": "#0A09084D", "$type": "color", "$description": "30% ink — for hairline rules" }, + "accent": { "$value": "#B91C1C", "$type": "color", "$description": "Editorial red — single sharp accent" }, + "muted": { "$value": "#6B6760", "$type": "color", "$description": "Caption / metadata text" } + }, + "color-dark": { + "ink": { "$value": "#FAF8F3", "$type": "color" }, + "paper": { "$value": "#0A0908", "$type": "color" }, + "rule": { "$value": "#FAF8F333","$type": "color" }, + "accent": { "$value": "#F87171", "$type": "color" }, + "muted": { "$value": "#A8A29E", "$type": "color" } + }, + "typography": { + "display": { "$value": { "fontFamily": "PP Editorial New", "fontSize": "clamp(48px, 9vw, 144px)", "fontWeight": 400, "lineHeight": 0.95, "letterSpacing": "-0.02em" }, "$type": "typography" }, + "headline": { "$value": { "fontFamily": "PP Editorial New", "fontSize": "clamp(32px, 5vw, 72px)", "fontWeight": 400, "lineHeight": 1.05, "letterSpacing": "-0.015em" }, "$type": "typography" }, + "title": { "$value": { "fontFamily": "PP Editorial New", "fontSize": "32px", "fontWeight": 500, "lineHeight": 1.15 }, "$type": "typography" }, + "body": { "$value": { "fontFamily": "PP Neue Montreal", "fontSize": "18px", "fontWeight": 400, "lineHeight": 1.55 }, "$type": "typography" }, + "small": { "$value": { "fontFamily": "PP Neue Montreal", "fontSize": "14px", "fontWeight": 400, "lineHeight": 1.45 }, "$type": "typography" }, + "metadata": { "$value": { "fontFamily": "PP Neue Montreal Mono", "fontSize": "12px", "fontWeight": 400, "letterSpacing": "0.06em", "textTransform": "uppercase" }, "$type": "typography" } + }, + "spacing": { + "$description": "Asymmetric — varied rhythm, not uniform py-20", + "tight": { "$value": "16px", "$type": "dimension" }, + "snug": { "$value": "32px", "$type": "dimension" }, + "rest": { "$value": "64px", "$type": "dimension" }, + "breath": { "$value": "120px","$type": "dimension" }, + "room": { "$value": "200px","$type": "dimension" } + }, + "radius": { + "$description": "Editorial direction: 0 radius is a feature", + "none": { "$value": "0", "$type": "dimension" }, + "subtle": { "$value": "2px","$type": "dimension" } + }, + "motion": { + "spring-default": { "$value": "spring(stiffness: 300, damping: 30)", "$type": "string" }, + "stagger": { "$value": "50ms", "$type": "duration" } + }, + "noise": { + "$description": "Subtle grain overlay — adds tactility", + "url": { "$value": "url('/noise.svg')", "$type": "string" }, + "opacity": { "$value": "0.04", "$type": "number" } + } +} diff --git a/plugins/f0d010c/stark/assets/tokens/fluent-2.json b/plugins/f0d010c/stark/assets/tokens/fluent-2.json new file mode 100644 index 000000000..8691d887b --- /dev/null +++ b/plugins/f0d010c/stark/assets/tokens/fluent-2.json @@ -0,0 +1,74 @@ +{ + "$schema": "https://schemas.microsoft.com/fluent-design/tokens/v1.json", + "$description": "Microsoft Fluent 2 reference token bundle — DTCG W3C format. Translate to WinUI 3 ResourceDictionary via scripts/token_export.py.", + "color": { + "neutral": { + "background": { + "default": { "$value": "#F3F3F3", "$type": "color", "$description": "Light theme app background" }, + "default-dark": { "$value": "#202020", "$type": "color", "$description": "Dark theme app background" }, + "card": { "$value": "#FBFBFB", "$type": "color", "$description": "Card surface light" }, + "card-dark": { "$value": "#2B2B2B", "$type": "color", "$description": "Card surface dark" }, + "layer": { "$value": "#FFFFFFB3", "$type": "color", "$description": "Layer fill (Acrylic over content)" } + }, + "stroke": { + "default": { "$value": "#0000000F", "$type": "color" }, + "default-dark": { "$value": "#FFFFFF14", "$type": "color" }, + "card-default": { "$value": "#0000000F", "$type": "color" }, + "divider": { "$value": "#00000017", "$type": "color" } + }, + "foreground": { + "primary": { "$value": "#000000E4", "$type": "color", "$description": "Light primary text" }, + "primary-dark": { "$value": "#FFFFFF", "$type": "color", "$description": "Dark primary text" }, + "secondary": { "$value": "#0000009E", "$type": "color" }, + "tertiary": { "$value": "#0000007A", "$type": "color" }, + "disabled": { "$value": "#00000040", "$type": "color" } + } + }, + "accent": { + "default": { "$value": "#0F6CBD", "$type": "color", "$description": "Brand Communication primary" }, + "hover": { "$value": "#0E5BAA", "$type": "color" }, + "pressed": { "$value": "#0C4A8E", "$type": "color" } + }, + "semantic": { + "success": { "$value": "#107C10", "$type": "color" }, + "warning": { "$value": "#FFB900", "$type": "color" }, + "danger": { "$value": "#C42B1C", "$type": "color" }, + "info": { "$value": "#0F6CBD", "$type": "color" } + } + }, + "spacing": { + "none": { "$value": "0", "$type": "dimension" }, + "xxxs": { "$value": "2px", "$type": "dimension" }, + "xxs": { "$value": "4px", "$type": "dimension" }, + "xs": { "$value": "8px", "$type": "dimension" }, + "s": { "$value": "12px","$type": "dimension" }, + "m": { "$value": "16px","$type": "dimension" }, + "l": { "$value": "20px","$type": "dimension" }, + "xl": { "$value": "24px","$type": "dimension" }, + "xxl": { "$value": "32px","$type": "dimension" }, + "xxxl": { "$value": "48px","$type": "dimension" } + }, + "radius": { + "none": { "$value": "0", "$type": "dimension" }, + "small": { "$value": "4px", "$type": "dimension", "$description": "Default control radius" }, + "medium": { "$value": "8px", "$type": "dimension", "$description": "Window radius" }, + "large": { "$value": "12px","$type": "dimension" } + }, + "typography": { + "caption": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "12px", "lineHeight": "16px", "fontWeight": 400 }, "$type": "typography" }, + "body": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "14px", "lineHeight": "20px", "fontWeight": 400 }, "$type": "typography" }, + "body-strong": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "14px", "lineHeight": "20px", "fontWeight": 600 }, "$type": "typography" }, + "body-large": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "18px", "lineHeight": "24px", "fontWeight": 400 }, "$type": "typography" }, + "subtitle": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "20px", "lineHeight": "28px", "fontWeight": 600 }, "$type": "typography" }, + "title": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "28px", "lineHeight": "36px", "fontWeight": 600 }, "$type": "typography" }, + "title-large": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "40px", "lineHeight": "52px", "fontWeight": 600 }, "$type": "typography" }, + "display": { "$value": { "fontFamily": "Segoe UI Variable", "fontSize": "68px", "lineHeight": "92px", "fontWeight": 600 }, "$type": "typography" } + }, + "duration": { + "ultra-fast": { "$value": "50ms", "$type": "duration" }, + "faster": { "$value": "100ms", "$type": "duration" }, + "fast": { "$value": "150ms", "$type": "duration" }, + "normal": { "$value": "250ms", "$type": "duration" }, + "slow": { "$value": "400ms", "$type": "duration" } + } +} diff --git a/plugins/f0d010c/stark/assets/tokens/material3-expressive.json b/plugins/f0d010c/stark/assets/tokens/material3-expressive.json new file mode 100644 index 000000000..d8a3a3c89 --- /dev/null +++ b/plugins/f0d010c/stark/assets/tokens/material3-expressive.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://m3.material.io/schemas/tokens.json", + "$description": "Material 3 Expressive reference tokens (May 2026). Includes shape-morph, motion-scheme-expressive, wavy-amplitude. Translate to Compose ColorScheme + Typography + MotionScheme via scripts/token_export.py.", + "color": { + "primary": { "$value": "#6750A4", "$type": "color" }, + "on-primary": { "$value": "#FFFFFF", "$type": "color" }, + "primary-container": { "$value": "#EADDFF", "$type": "color" }, + "on-primary-container": { "$value": "#21005D", "$type": "color" }, + "secondary": { "$value": "#625B71", "$type": "color" }, + "on-secondary": { "$value": "#FFFFFF", "$type": "color" }, + "tertiary": { "$value": "#7D5260", "$type": "color" }, + "error": { "$value": "#B3261E", "$type": "color" }, + "background": { "$value": "#FFFBFE", "$type": "color" }, + "surface": { "$value": "#FFFBFE", "$type": "color" }, + "surface-variant": { "$value": "#E7E0EC", "$type": "color" }, + "outline": { "$value": "#79747E", "$type": "color" }, + "outline-variant": { "$value": "#CAC4D0", "$type": "color" } + }, + "color-dark": { + "primary": { "$value": "#D0BCFF", "$type": "color" }, + "background": { "$value": "#1C1B1F", "$type": "color" }, + "surface": { "$value": "#1C1B1F", "$type": "color" } + }, + "shape": { + "none": { "$value": "0px", "$type": "dimension" }, + "extra-small": { "$value": "4px", "$type": "dimension" }, + "small": { "$value": "8px", "$type": "dimension" }, + "medium": { "$value": "12px", "$type": "dimension" }, + "large": { "$value": "16px", "$type": "dimension" }, + "extra-large": { "$value": "28px", "$type": "dimension" }, + "full": { "$value": "9999px","$type": "dimension" }, + "morph": { + "$description": "M3E shape-morphing — name → MaterialShapes constant", + "cookie-4": { "$value": "MaterialShapes.Cookie4Sided", "$type": "string" }, + "cookie-6": { "$value": "MaterialShapes.Cookie6Sided", "$type": "string" }, + "cookie-9": { "$value": "MaterialShapes.Cookie9Sided", "$type": "string" }, + "cookie-12": { "$value": "MaterialShapes.Cookie12Sided","$type": "string" }, + "pill": { "$value": "MaterialShapes.Pill", "$type": "string" }, + "boom": { "$value": "MaterialShapes.Boom", "$type": "string" }, + "burst": { "$value": "MaterialShapes.Burst", "$type": "string" }, + "clover-4": { "$value": "MaterialShapes.Clover4Leaf", "$type": "string" }, + "clover-8": { "$value": "MaterialShapes.Clover8Leaf", "$type": "string" }, + "clamshell": { "$value": "MaterialShapes.Clamshell", "$type": "string" } + } + }, + "spacing": { + "$description": "4dp grid", + "0": { "$value": "0", "$type": "dimension" }, + "1": { "$value": "4dp", "$type": "dimension" }, + "2": { "$value": "8dp", "$type": "dimension" }, + "3": { "$value": "12dp", "$type": "dimension" }, + "4": { "$value": "16dp", "$type": "dimension" }, + "5": { "$value": "20dp", "$type": "dimension" }, + "6": { "$value": "24dp", "$type": "dimension" }, + "8": { "$value": "32dp", "$type": "dimension" } + }, + "typography": { + "display-large": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "57sp", "lineHeight": "64sp", "fontWeight": 400 }, "$type": "typography" }, + "display-medium": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "45sp", "lineHeight": "52sp", "fontWeight": 400 }, "$type": "typography" }, + "headline-large": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "32sp", "lineHeight": "40sp", "fontWeight": 600 }, "$type": "typography", "$description": "M3E — emphasized heavier than baseline M3" }, + "headline-medium": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "28sp", "lineHeight": "36sp", "fontWeight": 600 }, "$type": "typography" }, + "title-large": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "22sp", "lineHeight": "28sp", "fontWeight": 600 }, "$type": "typography" }, + "title-medium": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "16sp", "lineHeight": "24sp", "fontWeight": 600 }, "$type": "typography" }, + "body-large": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "16sp", "lineHeight": "24sp", "fontWeight": 400 }, "$type": "typography" }, + "body-medium": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "14sp", "lineHeight": "20sp", "fontWeight": 400 }, "$type": "typography" }, + "label-large": { "$value": { "fontFamily": "Roboto Flex", "fontSize": "14sp", "lineHeight": "20sp", "fontWeight": 600 }, "$type": "typography" } + }, + "motion": { + "$description": "M3 Expressive — spring physics replace easing curves", + "scheme": { "$value": "MotionScheme.expressive()", "$type": "string" }, + "spring-fast-spatial": { "$value": "{ stiffness: 1400, damping: 0.9 }", "$type": "string" }, + "spring-default-spatial": { "$value": "{ stiffness: 800, damping: 0.8 }", "$type": "string" }, + "spring-slow-spatial": { "$value": "{ stiffness: 200, damping: 0.8 }", "$type": "string" }, + "duration-fast": { "$value": "150ms", "$type": "duration", "$description": "Use only when a spring isn't appropriate (color/alpha)" }, + "duration-medium": { "$value": "300ms", "$type": "duration" }, + "duration-slow": { "$value": "500ms", "$type": "duration" } + }, + "elevation": { + "$description": "M3E — tonal elevation only. Drop shadow is BANNED on M3E surfaces.", + "level0": { "$value": "0", "$type": "dimension", "$description": "No tonal shift" }, + "level1": { "$value": "1dp", "$type": "dimension", "$description": "Surface +5% primary tone" }, + "level2": { "$value": "3dp", "$type": "dimension" }, + "level3": { "$value": "6dp", "$type": "dimension" }, + "level4": { "$value": "8dp", "$type": "dimension" }, + "level5": { "$value": "12dp","$type": "dimension" } + }, + "wavy-progress": { + "$description": "M3E LinearWavyProgressIndicator amplitude tokens", + "default": { "$value": "8dp", "$type": "dimension" }, + "tight": { "$value": "4dp", "$type": "dimension" }, + "expressive":{ "$value": "12dp","$type": "dimension" } + } +} diff --git a/plugins/f0d010c/stark/commands/stark-assets.md b/plugins/f0d010c/stark/commands/stark-assets.md new file mode 100644 index 000000000..984f4ddbc --- /dev/null +++ b/plugins/f0d010c/stark/commands/stark-assets.md @@ -0,0 +1,41 @@ +--- +description: Plan UI assets for a Stark design before implementation, including references, icons, typography, generated product mocks, and optional image generation when the agent supports it. +argument-hint: "" +--- + +# /stark-assets + +Legacy Claude Code command. +In Codex, ask: + +> Use stark assets to plan the visual assets for this app/site before building. + +Plan assets for the project described by `$ARGUMENTS`. + +Read: + +- `references/ui-patterns/ui-decision-brief.md` +- `references/ui-patterns/asset-selection.md` +- the routed platform or web skill + +Then produce an asset plan before implementation: + +```md +Asset plan +- Needed assets: product UI mock, icons, texture, typeface, references +- Source: local Stark library, lucide, generated CSS/SVG mock, imagegen, external reference +- License risk: none / low / needs attribution / avoid +- Usage: hero product preview, warning states, workflow diagram, empty state +- Reference extraction: structure only, not copied visuals +- Bans: stock hero photos, abstract AI gradients, placeholder images, private screenshots without permission +``` + +## Rules + +- Do not freely browse and grab assets. +- Ask whether the project needs icons, real product screenshots, reference UI patterns, typography, brand assets, or generated bitmap visuals. +- Pull only assets that support the product job and visual direction. +- If the agent is GPT/Codex and image generation is available, prefer generated bitmap assets for fictional hero imagery, textures, product concept art, or editorial visuals when CSS/SVG would be too weak. +- Never include private/local screenshots unless the user explicitly allows it. +- Do not copy copyrighted brand assets into public output. +- Use real-world references to extract structure and interaction patterns, not visual identity. diff --git a/plugins/f0d010c/stark/commands/stark-audit.md b/plugins/f0d010c/stark/commands/stark-audit.md new file mode 100644 index 000000000..b6b7a40c8 --- /dev/null +++ b/plugins/f0d010c/stark/commands/stark-audit.md @@ -0,0 +1,50 @@ +--- +description: Audit existing UI/UX code, flows, or screenshots against UX heuristics plus the matching platform's anti-slop ban list and idiomatic checklist. Reports specific violations with line numbers and proposed fixes. +argument-hint: "[file or screenshot path]" +--- + +# /stark-audit + +Legacy Claude Code command. +In Codex, ask: + +> Audit this file with stark for UX problems and AI design slop. + +Audit the file or screenshot at `$1` against the appropriate platform's standards from this plugin. + +Steps: + +1. **Detect platform** from file extension or screenshot context: + - `.tsx`/`.jsx`/`.html`/`.svelte`/`.vue`/`.astro` → web + - `.xaml`/`.cs` (with WinUI/WPF context) → windows + - `.swift` → apple + - `.kt`/`.kts` → android + - Screenshot → infer from chrome (title bar style, icons, materials) + +2. **Load UX checks first when the artifact includes a workflow, form, dashboard, onboarding, checkout, settings, or multi-step task**: + - UX -> `skills/ux-design/SKILL.md` audit checklist + - UI -> `references/ui-patterns/ui-audit-rubric.md` + - Assets -> `references/ui-patterns/asset-selection.md` when the artifact uses images, screenshots, icons, generated visuals, external references, or brand assets + - References -> `references/ui-patterns/reference-analysis.md` when the artifact claims to use a real product, Mobbin, Figma, or screenshot reference + +3. **Load the matching ban list**: + - web → `references/web-bans.md` + - windows → `skills/windows-design/SKILL.md` step 6 + - apple → `skills/apple-design/SKILL.md` step 6 + - android → `skills/android-design/SKILL.md` step 6 + +4. **Walk the file** and report violations as a table: + + | Line | Violation | Severity | Fix | + |---|---|---|---| + | 42 | `bg-gradient-to-r from-purple-500 to-pink-500` (banned web slop) | high | Pick a real direction; see web-fonts.md | + | 88 | `font-family: 'Inter'` (banned default) | high | Replace with a curated pair from `assets/font-pairs.md` | + +5. **Categorize** violations: + - **High** — blocked primary job, missing recovery path, unsafe/destructive action, broken platform idiom, or definitive AI slop tell + - **Medium** — missing state, weak action hierarchy, generic pattern that hurts distinctiveness, decorative assets that do not support the job, or repeated-use friction + - **Low** — unclear copy, mild scan-speed issue, or currency issue (using older patterns when newer ones exist) + +6. **Recommend a fix path**: one paragraph, concrete steps, no hedging. + +Do not just list violations. Always include the fix. If the entire approach needs rework, say so plainly. Prioritize broken flow, missing states, unclear next actions, and accessibility before visual distinctiveness. diff --git a/plugins/f0d010c/stark/commands/stark-reference.md b/plugins/f0d010c/stark/commands/stark-reference.md new file mode 100644 index 000000000..ea5545a7b --- /dev/null +++ b/plugins/f0d010c/stark/commands/stark-reference.md @@ -0,0 +1,38 @@ +--- +description: Analyze real shipped UI/UX references without copying visuals, then produce a structural reference extraction brief for Stark. +argument-hint: "" +--- + +# /stark-reference + +Legacy Claude Code command. +In Codex, ask: + +> Use stark reference analysis for this flow before designing. + +Read: + +- `references/ui-patterns/reference-analysis.md` +- `references/ui-patterns/asset-selection.md` +- the relevant UX or platform skill + +Inspect 3-5 shipped references when available. Use official docs, live public pages, first-party screenshots, or approved reference libraries. If using Mobbin/Figma/reference screenshots, extract structure only. + +Output: + +```md +Reference extraction brief +- Pattern chosen: ... +- Why it fits this user's job: ... +- Structural decisions to borrow: ... +- Decisions to reject: ... +- State/responsive requirements: ... +- Asset/source constraints: ... +``` + +Rules: + +- Do not pixel-clone. +- Do not copy brand, artwork, screenshots, copy, or proprietary layouts. +- Name what you learned from each reference in product terms: job, IA, hierarchy, state, interaction, recovery, responsive behavior. +- Use the brief as input to UX/UI implementation. diff --git a/plugins/f0d010c/stark/commands/stark-translate.md b/plugins/f0d010c/stark/commands/stark-translate.md new file mode 100644 index 000000000..a35225fbb --- /dev/null +++ b/plugins/f0d010c/stark/commands/stark-translate.md @@ -0,0 +1,39 @@ +--- +description: Translate a UI from one platform's idiom to another's — same product, different idiom — respecting target platform's HIG/Material/Fluent rather than pixel-cloning. e.g., "translate this iOS Settings screen to Windows". +argument-hint: "[from-platform] [to-platform] " +--- + +# /stark-translate + +Legacy Claude Code command. +In Codex, ask: + +> Translate this Apple UI to Windows using stark. + +Translate UI from `$1` (source platform) to `$2` (target platform), preserving product semantics but using the target platform's idiom. + +Source/target must each be one of: `web`, `windows`, `apple`, `android`. + +## Process + +1. **Read the source** — file content or description from `$ARGUMENTS` after the platform args. + +2. **Identify the product semantics** — what is this UI doing? Settings? List-detail? Onboarding? Tab nav? Modal flow? + +3. **Translate idiom, not pixels**. Reference the translation rules in `skills/cross-platform-design/SKILL.md` step 3. + + Example: an iOS grouped Form with switch toggles becomes: + - On Windows → `NavigationView` + scrollable stack of `SettingsCard` over Mica + - On Android → `LargeTopAppBar` + `LazyColumn` with `ListItem` rows + M3 switches + - On web → asymmetric layout with sidebar nav and editorial section headers + +4. **Apply target platform's anti-slop ban list** as you generate. Read the target's SKILL.md step 6. + +5. **State the translation choices** at the top of the response in 2–3 lines: + - "iOS grouped Form → Windows NavigationView + SettingsCard stack with Mica backdrop" + - "iOS Toggle → WinUI ToggleSwitch with ThemeResource brushes" + - "iOS section headers → Windows muted text headers, no row separators" + +6. **Implement** working code in the target stack. + +Refuse to pixel-clone. If the user insists on identical pixels across platforms, push back once with the rationale: every platform has reference apps that nail their idiom; users notice when a Mac app feels Android. diff --git a/plugins/f0d010c/stark/commands/stark.md b/plugins/f0d010c/stark/commands/stark.md new file mode 100644 index 000000000..04b6e730a --- /dev/null +++ b/plugins/f0d010c/stark/commands/stark.md @@ -0,0 +1,31 @@ +--- +description: Generate or improve UI/UX for the specified platform - ux, web, windows, apple, android, or cross-platform. Routes to matching skill which then asks the user which product flow, track, or aesthetic direction before generating code. +argument-hint: "[platform] " +--- + +# /stark + +Legacy Claude Code command. +In Codex, use natural language instead: + +> Use stark ux-design to improve the onboarding flow. +> Use stark web-design for a developer-tool landing page. +> Use stark windows-design for a WinUI music app. + +Generate or improve UI/UX for the platform specified by `$1` and the description in the rest of the arguments. + +`$1` must be one of: `ux`, `web`, `windows`, `apple`, `ios`, `macos`, `android`, `cross-platform`, or `auto` (let the router pick). + +Then read the matching SKILL.md from `skills/`: + +- `ux` -> `skills/ux-design/SKILL.md` - maps product flow, states, IA, forms, onboarding, dashboards, and repeated-use ergonomics +- `web` -> `skills/web-design/SKILL.md` - asks aesthetic direction + stack first +- `windows` -> `skills/windows-design/SKILL.md` - asks track first (system / branded / Tauri / Electron) +- `apple` / `ios` / `macos` -> `skills/apple-design/SKILL.md` - asks track first (SwiftUI / RN / Flutter / Tauri / Electron) +- `android` -> `skills/android-design/SKILL.md` - asks track first (Compose / RN / Flutter / CMP) +- `cross-platform` -> `skills/cross-platform-design/SKILL.md` +- `auto` -> `skills/design-router/SKILL.md` + +Follow that SKILL.md's full process. Do not skip the upfront decisions. Ask product job, track, or direction before any code when unclear. If UX applies, produce the UX decision brief first and preserve it through platform implementation. For build/redesign work, also produce the UI decision brief from `references/ui-patterns/ui-decision-brief.md`. If assets matter, read `commands/stark-assets.md` and produce an asset plan. If shipped references matter, read `commands/stark-reference.md` and produce a reference extraction brief. State the chosen route at the top of the response. Then implement. + +If the user did not specify enough context (audience, tone, constraints), ask one clarifying question before generating. Do not assume defaults silently. diff --git a/plugins/f0d010c/stark/docs/review-contract.md b/plugins/f0d010c/stark/docs/review-contract.md new file mode 100644 index 000000000..1c178dfab --- /dev/null +++ b/plugins/f0d010c/stark/docs/review-contract.md @@ -0,0 +1,62 @@ +# Review contract + +This document defines what Stark promises to ship and test. + +## Runtime bundle + +The Codex plugin runtime bundle is intentionally limited to files used by installed skills: + +- `.codex-plugin/plugin.json` +- `skills/` +- `references/` +- `assets/` +- `commands/` +- `docs/review-contract.md` +- `agents/` +- `scripts/detect_platform.py` +- `scripts/token_export.py` + +## Local-only files + +These are source-repo or maintainer files, not required in marketplace installs: + +- `tests/` +- `.github/` +- generated app examples +- Playwright/browser screenshot helpers +- temporary screenshots +- archive folders + +## Helper script contract + +`scripts/detect_platform.py` must route: + +- explicit single-platform prompts to that named platform +- explicit multi-platform or shared-codebase prompts to `cross-platform` +- platform-free prompts to `ambiguous` + +`scripts/token_export.py` must support only the documented targets: + +- `tailwind` +- `css` +- `swiftui` +- `compose` +- `winui` + +Do not document additional token targets unless the exporter implements and tests them. + +Token export must preserve: + +- group-level DTCG `$type` inheritance +- nested reference resolution inside composite values +- circular-reference detection +- Tailwind v4 namespace-friendly names +- Compose `ColorScheme` and `Typography` +- SwiftUI color/font output with line-height companion constants +- WinUI alpha-first color conversion + +## Change policy + +Design guidance changes are low risk and can ship as patch releases when they do not alter helper behavior. + +Helper script changes are higher risk and must include focused tests before release. Avoid expanding script scope inside marketplace-listing PRs unless the new behavior is required by existing docs. diff --git a/plugins/f0d010c/stark/references/apple-hig.md b/plugins/f0d010c/stark/references/apple-hig.md new file mode 100644 index 000000000..b4c9fddd2 --- /dev/null +++ b/plugins/f0d010c/stark/references/apple-hig.md @@ -0,0 +1,125 @@ +# Apple HIG — Quick Reference (May 2026) + +Source of truth: https://developer.apple.com/design/human-interface-guidelines + +This file extracts the rules that most affect generated UI. Read for grounding when output feels "non-Apple." + +## Foundations + +### Layout +- Base grid: **8 pt**, half-step **4 pt** +- Never use 10/15/20 spacing magic numbers — they break the system +- Use `.padding()` defaults — they encode the system grid +- Wrap every screen with safe area handling: `.safeAreaInset(edge:)` for content bars + +### Typography +- Default face: **SF Pro** (Display + Text variants), **SF Pro Rounded**, **SF Mono**, **New York** (serif) +- Use `Font.TextStyle`, never hard-coded points: + - `.largeTitle` (34pt) + - `.title` (28pt) + - `.title2` (22pt) + - `.title3` (20pt) + - `.headline` (17pt semibold) + - `.body` (17pt) + - `.callout` (16pt) + - `.subheadline` (15pt) + - `.footnote` (13pt) + - `.caption` (12pt) + - `.caption2` (11pt) +- **Dynamic Type**: support `xSmall` → `AX5`. Test at AX5. If layout breaks, redesign. + +### Color +- **Use system semantic colors**, not raw hex: + - `.primary` (label) + - `.secondary` + - `.tint` (app accent) + - `Color(.systemBackground)`, `.systemGray`, `.systemGray2`...`.systemGray6` + - `Color(.systemRed)`, `.systemBlue`, etc. +- These adapt automatically to light/dark and accessibility contrast settings. +- For brand color: define a single `accentColor` in the asset catalog, reference via `.tint(.accentColor)`. + +### SF Symbols 7 +- ~6,900 glyphs, 9 weights × 3 scales +- New in SF Symbols 7: Draw On/Off, Variable Draw, gradients, enhanced Magic Replace +- Use `Image(systemName: "...")`, never custom icon files when an SF Symbol exists +- Symbol effects: `.symbolEffect(.bounce)`, `.pulse`, `.variableColor`, `.replace.byLayer`, `.appear`, `.disappear` + +### Materials +- `.regularMaterial` — default toolbar/sidebar +- `.ultraThinMaterial`, `.thinMaterial`, `.thickMaterial`, `.ultraThickMaterial` +- On iOS 26+, add Liquid Glass via `.glassEffect()` (see `liquid-glass.md`) + +### Motion +- **Spring physics only** for UI motion +- `.animation(.spring(response:dampingFraction:), value:)` +- Never linear / easeIn / easeOut on UI surfaces +- Respect `@Environment(\.accessibilityReduceMotion)` — disable non-essential motion + +### Accessibility (mandatory) +- `.accessibilityLabel("...")`, `.accessibilityHint("...")`, `.accessibilityValue("...")` +- `.accessibilityElement(children: .combine)` to group +- Traits: `.isButton`, `.isHeader`, `.isImage`, `.isLink`, `.isSelected`, `.updatesFrequently` +- VoiceOver test pass mandatory +- Support **Dynamic Type AX5**, **Reduce Motion**, **Increase Contrast**, **Reduce Transparency** + +## Patterns + +### Navigation +- **Hierarchy**: `NavigationStack { ... }` (push-pop) +- **Tabs**: `TabView { ... }` (5 max on iOS, 7 on iPad/Mac) +- **Split**: `NavigationSplitView { sidebar } content: { ... } detail: { ... }` for iPad/Mac +- **Inspector** (Mac/iPad): `.inspector { ... }` trailing pane +- **Modal**: `.sheet(isPresented:)` with `.presentationDetents([.medium, .large])` +- **Popover** (iPad/Mac): `.popover(isPresented:)` +- **Menu Bar Extra** (Mac): `MenuBarExtra("Name", systemImage: ...) { ... }` +- **Settings scene** (Mac): `Settings { TabView { ... } }` + +### Lists & Forms +- `List { ... }` with `.listStyle(.insetGrouped)` for grouped (iOS Settings pattern) +- `Form { Section("Header") { ... } }` for settings/forms +- `Toggle("Label", isOn: $value)` — never custom switches +- `Picker(...)` for selection — system handles iOS wheel, Mac dropdown automatically + +### Search +- `.searchable(text: $query, prompt: "...")` — morphs into Liquid Glass pill on iOS 26 +- `.searchSuggestions { ... }` for autocomplete + +## Inputs + +- `TextField`, `SecureField`, `TextEditor` — wrap in `.textFieldStyle(.roundedBorder)` only outside Form +- Inside Form, default style is correct +- `.keyboardType(.emailAddress)`, `.textContentType(.emailAddress)`, `.autocapitalization(.never)` +- `.submitLabel(.search)` for keyboard return-key customization + +## macOS specifics + +- Window styles via `.windowStyle(.titleBar)`, `.hiddenTitleBar`, `.plain` +- Toolbar customization: `.toolbar { ToolbarItem(placement: .primaryAction) { ... } }` +- Sidebar: list with `.listStyle(.sidebar)` inside `NavigationSplitView` +- Inspector pane: `.inspector { ... }` (Craft, Notes, Reminders pattern) +- Drop into AppKit only for: `NSTextView` rich text, Quick Look extensions, `NSToolbar` items, `NSOpenPanel` extensions + +## Reference apps to emulate + +| App | What it nails | +|---|---| +| Things 3 | Typography restraint, magic-plus, perfect Dynamic Type | +| Reeder Classic / 5 | NavigationSplitView on iPad/Mac | +| Ivory | HIG-correct + bespoke; haptic + symbolEffect | +| Mela | Text-first, native share sheets | +| Craft | Multi-pane Mac, inspector, vibrancy | +| NetNewsWire | Open-source HIG textbook | +| Soulver 3 | Mac typography + sidebar | +| CARROT Weather | System materials + variable color symbols | +| Overcast | Type hierarchy, Dynamic Type, accessibility | +| Fantastical | Sidebar + inspector + menu-bar mode | + +## Tokens & assets + +- iOS 26 Figma kit: https://www.figma.com/community/file/1527721578857867021/ios-and-ipados-26 +- macOS 26 Figma kit: https://www.figma.com/community/file/1543337041090580818/apple-design-resources-macos-26 +- SF Symbols 7 app: https://developer.apple.com/sf-symbols +- Apple Design Resources: https://developer.apple.com/design/resources +- HIG: https://developer.apple.com/design/human-interface-guidelines + +Token JSON: `assets/tokens/apple-system.json` diff --git a/plugins/f0d010c/stark/references/awwwards-ceiling.md b/plugins/f0d010c/stark/references/awwwards-ceiling.md new file mode 100644 index 000000000..566e314be --- /dev/null +++ b/plugins/f0d010c/stark/references/awwwards-ceiling.md @@ -0,0 +1,101 @@ +# Awwwards Ceiling — Web Quality Bar (2026) + +Reference points the web-design skill targets. **Group references by direction.** When picking refs to mention, pull from the matching direction. + +## Site of the Year tier (genre-defining) + +- **Lando Norris official site** (OFF+BRAND) — Awwwards SOTY 2025. Lime-green oversized type, scroll-driven cinema, 3D helmet. +- **igloo.inc** — 3D craft, generative environments, mega-type +- **studiofreight.com** — interactive studio ceiling, custom motion language +- **lusion.co** — bespoke WebGL, art-direction-as-product +- **active-theory.com** — WebGL studio ceiling +- **antinomy.studio** — Awwwards SOTM-tier brand site +- **off-brand.work** — design studio editorial + +## Direction-grouped refs + +### Editorial Swiss revival +- rauchg.com — tech blog, restraint +- are.na — editorial network, monospace metadata +- robinrendle.com — letters as objects +- maggieappleton.com — illustrated essays +- the-pudding.cool — long-form data editorial +- shauninman.com — paragraph-driven blog +- editorialnew.com (Pangram Pangram type foundry showcase) +- Artifact Labs (`assets/screenshots/artifact-labs-site/`) — our editorial sample + +### Tactile brutalism +- werkstatt.fyi — brutalist editorial +- fram.io — DIY/tape aesthetic +- off-brand.work — studio brutalism +- dinamo.us — type foundry brutalist +- pentagram.com (selected projects) — restrained brutalism +- ableton.com (loop sections) — Swiss brutalism +- read.cv (early versions) — terminal-meets-resume + +### Type-as-hero +- igloo.inc — Awwwards SOTY 2025 (3D + massive type) +- lehman.berlin — restraint + signature display +- Lando Norris site — Awwwards SOTY-tier +- pangrampangram.com — type foundry, type IS product +- ohnotype.co — display type w/ specimen heroes +- newedge.studio — display-driven brand +- monumentvalleygame.com — game site, type flex +- type.today — type foundry, type-led + +### Glow + grain +- stripe.com / stripe.com/sessions — gradient mastery +- openai.com — restrained atmospheric dark +- vercel.com hero — animated gradient + grid +- liveblocks.io — Awwwards-tier glow motion +- runwayml.com — generative atmosphere +- midjourney.com — soft glow, dreamy +- linear.app — restrained glow + craft +- arc.net (browser.company) — color-glow brand + +### Industrial monospace +- railway.com — serious editorial polish on technical content +- fly.io — terminal-driven brand +- raycast.com — dark craft, micro-interactions +- resend.com — type-driven dev tool benchmark +- supabase.com (older versions) +- modal.com — clean technical +- temporal.io — technical content, mono accents +- ngrok.com — terminal-meets-marketing + +### Active bento +- linear.app/method — bento tiles that expand on hover +- vercel.com/templates — bento gallery +- arc.net — interactive feature tiles +- raycast.com (extensions section) — bento-style +- notion.com (features) — animated bento +- fly.io (architecture page) — technical bento +- replit.com (homepage) — feature tiles +- supabase.com (features grid) — animated bento + +## Long-form scroll storytelling (special category) + +- apple.com/iphone — long-form scroll-driven storytelling, gold standard +- nike.com (campaign sites) — narrative scroll +- spaceperspective.com — scroll cinema +- formula1.com (campaign launches) + +## Editorial / brand sites + +- stan.vision — opinionated SaaS journal +- the.studio (selected brand sites) +- 1stuff.com — editorial brand + +## Self-check + +Before shipping any web generation: + +1. Does this fit alongside refs from the matching direction? +2. Is the type distinctive (not Inter / Space Grotesk)? +3. Are there 2-4 signature motion moments? +4. Does the layout break "hero + 3-column features + CTA"? +5. Dark mode has warmth/coolness, not inversion? +6. Did I avoid every item in `web-bans.md`? +7. Did I avoid every phrase in `web-copy-voice.md` ban list? + +If any "no" — restart that choice, don't ship near-misses. diff --git a/plugins/f0d010c/stark/references/branded-fluent.md b/plugins/f0d010c/stark/references/branded-fluent.md new file mode 100644 index 000000000..be4bb3998 --- /dev/null +++ b/plugins/f0d010c/stark/references/branded-fluent.md @@ -0,0 +1,188 @@ +# Branded Fluent — When and How to Look Original on Windows + +The most common failure of Windows-design AI output is shipping apps that look exactly like Settings. Fluent is a *system*, not a *visual style*. You can theme it heavily and still be canonically native. + +The opposite failure is going Electron — rejecting the platform. Mica gone, ThemeResource gone, Snap Layouts broken, accessibility broken. Foreign. + +This doc covers the middle path: branded Fluent. Apple Music for Windows, Files (community), PowerToys redesign, Notepad rewrite, Microsoft Store, DevHome — all use WinUI 3 + Mica + ThemeResource discipline, but feel like distinct products. + +## Decide: branded or system-like? + +| Build branded if | Build system-like if | +|---|---| +| Consumer / media / creative app | Productivity / system utility | +| Brand identity is a deliverable | Settings panel, control panel-style tool | +| Marketing site exists | Internal tool | +| Has a name + logo | "Just works" tool | +| User picks vibe | User picks function | + +Examples branded: Files, Apple Music for Windows, Spotify (if they used WinUI), a markdown editor, a music player, a photo viewer, a chat client. + +Examples system-like: PowerToys (intentionally — its identity *is* "official Microsoft utility"), Snipping Tool, Notepad, Sound Recorder. + +## What branding IS allowed within Fluent + +### 1. Custom accent color +Override `SystemAccentColor` (or `SystemAccentColorLight*`/`Dark*`) in `App.xaml`. Stake out a brand color. Example: Resonance uses deep red `#C53030`. Cards/buttons/sliders/toggles all pick it up automatically. + +```xml + + + + + + #C53030 + #E53E3E + #FC8181 + #9B2C2C + #742A2A + + + #C53030 + + + #FC8181 + + + + +``` + +### 2. Custom display typography (alongside Segoe) +Keep Segoe UI Variable for **system surfaces** (settings rows, dialogs, menus, captions) — those need to feel native. Add a brand display face for **hero content** — page titles, album/article/post hero, marketing surfaces. + +```xml + +``` + +Pairings that work on Windows: +- **Newsreader** (Google Fonts, free) — neo-serif, editorial restraint +- **Bricolage Grotesque** (Google Fonts) — bold display grotesque, distinctive +- **Söhne** (Klim, paid) — gold-standard workhorse +- **PP Editorial New** (Pangram Pangram, paid) — magazine display +- **Inter Display** + Segoe body — modest improvement, common +- **Cascadia Code** — already shipped with Win11; great for monospace hero + +Never replace Segoe UI Variable in dialogs/menus/captions/system rows. Brand layer is for **content hero only**. + +### 3. Hero atmospheres +Default WinUI Settings = Mica + plain text. Branded apps add a hero atmosphere on the *content* surface (not the chrome): +- Mesh gradient backdrop (full-bleed, large, slow) +- Grain/noise overlay (`Image` of noise.png at 6–10% opacity) +- Glow/light streaks (radial gradients with low opacity) +- Layered material: Mica (window) + custom hero (content) — both can coexist + +```xml + + + + + + + + + + + + + +``` + +Apple Music for Windows does this brilliantly: full-bleed art-derived gradient under each track's hero, grain overlay, content typography on top. + +### 4. Custom card chrome +Default `SettingsCard` is the Settings-app give-away. Replace with custom card style for branded surfaces — keep it for actual settings rows. + +```xml + +``` + +### 5. Custom NavigationView selection indicator +Default rail uses pill-shaped accent indicator. Override: + +```xml + + + + 0,0,0,0 + 10 + +``` + +Or replace `NavigationView` with a fully custom rail — Files community does this, gets a distinctive sidebar with playlists/locations/tags layered. + +### 6. Custom motion language +Beyond ThemeResource transitions, add: +- **ConnectedAnimationService** for hero transitions (tap album in grid → it grows into NowPlaying hero — canonical Fluent connected animation) +- **Composition API** (`Microsoft.UI.Composition`) for blur, drop-shadow, parallax scroll +- **Implicit animations** on visibility/offset/opacity property changes +- Custom `TransitionCollection` on `Frame` (`SuppressNavigationTransitionInfo` + your own) + +### 7. Magazine / asymmetric layouts +Default WinUI = stacked rows / uniform grids. Branded = editorial. Album grid with hero tile + smaller tiles, asymmetric playlist covers, scroll-driven reveal. + +Use `ItemsRepeater` with `StackLayout` / `UniformGridLayout` / custom `Layout` subclass. Or absolute `Canvas` for art-direction-style heros. + +### 8. Custom illustration / iconography +- **Keep Segoe Fluent Icons** for system idioms (chevrons, settings gear, file glyph) — users know what they mean +- **Add brand iconography** for product surfaces — custom SVGs, illustration, photography +- Don't go FontAwesome / Material — those telegraph "this dev imported web assets" + +Apple Music for Windows uses Segoe Fluent for system + bespoke artwork for content. + +## Anti-patterns within branded Fluent + +- Replacing Segoe UI Variable globally with a custom font (breaks dialog/menu legibility, breaks accessibility) +- Removing ThemeResource brushes (breaks dark/light/HC) +- Custom title bar that breaks Snap Layouts hover +- Glassmorphism cards stacked over Mica (Mica is already a material — adding glass on top muddies) +- Drop shadows for elevation (use tonal elevation; only use shadow for hero modals) +- Removing focus rings (accessibility) +- Hardcoded hex everywhere (breaks dark mode adaptation) +- Replacing system controls with custom-painted ones (breaks accessibility, gestures, IME) + +## Branded Fluent reference apps + +Study these to see what "native but original" looks like in 2026: + +| App | What's branded | What stays native | +|---|---|---| +| **Files (community)** | Custom layout, brand color, custom sidebar, custom thumbnails | Mica, ThemeResource, Snap, accessibility, command bar | +| **Apple Music for Windows** | Hero atmospheres, art-driven gradients, custom typography, custom playback bar | Mica, NavigationView, ThemeResource, dialogs | +| **Spotify (web-wrapper, but architecturally similar)** | Brand green accent, custom sidebar, custom card chrome, image-rich content | (Not native — example of what NOT to do) | +| **PowerToys (Niels Laute redesign)** | Refined hierarchy, brand color subtly | Stays system-like — that's the intentional ID | +| **Notepad (rewrite)** | Minimal restraint, custom AI sidebar | Strict native everywhere else | +| **DevHome** | Dashboard widgets, branded cards | Native chrome | + +## Step-by-step: rebrand a Settings clone + +1. Pick a brand color (warm/cool, saturated, distinct from system blue). Override `SystemAccentColor`. +2. Pick a display font for hero content. Embed in `Assets/Fonts/`. Use ONLY for page titles + heroes. +3. Replace the default top-of-page "title + caption" pattern with a hero atmosphere (gradient + grain + bigger custom-font title). +4. Replace `SettingsCard` chrome on **non-settings** pages — only keep it on actual Settings. +5. Add a brand logo in the title bar (custom path, custom icon, or wordmark). +6. Customize NavigationView selection indicator (corner radius, color, hover effect). +7. Add at least one ConnectedAnimation between two pages. +8. Verify in dark mode, high contrast, and Narrator. None of the above should break those. + +## When to stop branding + +If your "branded" app stops feeling like it belongs on Windows, you've gone too far. Test: +- Title bar still respects Snap Layouts hover? +- Dark mode toggles correctly? +- High contrast still legible? +- Right-click context menus still native? +- Keyboard navigation works? +- Narrator reads the surface correctly? + +If any "no", pull branding back until they're "yes". diff --git a/plugins/f0d010c/stark/references/design-philosophy.md b/plugins/f0d010c/stark/references/design-philosophy.md new file mode 100644 index 000000000..368a53a38 --- /dev/null +++ b/plugins/f0d010c/stark/references/design-philosophy.md @@ -0,0 +1,71 @@ +# stark — Core Philosophy + +This document is loaded by SKILL.md files when a generation needs grounding. Read it when the user asks "why do you keep saying X" or when a generation feels generic. + +## Thesis + +Most AI-generated UI looks the same because LLMs converge on the math-average of design. The math-average is purple, indigo, Inter, Tailwind, shadcn, three-card grid, hero-with-two-buttons. It is technically correct and aesthetically dead. + +This skill exists to refuse the average. + +## Three principles + +### 1. Idiom over pixel + +A Settings screen is not a Settings screen. On iOS it is a grouped Form with switch toggles inside Liquid Glass Sections. On Android it is a `LargeTopAppBar` over a `LazyColumn`. On Windows it is a `NavigationView` with `SettingsCard` rows over Mica. On the web it is whatever the brand demands. + +Same product. Different pixels. The idiom is what makes a Mac app feel Mac and an Android app feel Android. Cloning iOS onto Android is the most common cross-platform failure mode and it's why Flutter apps always feel slightly wrong. + +### 2. Commit to a direction, then execute it precisely + +Maximalist works. Minimalist works. Refined editorial works. Tactile brutalism works. The middle does not work. + +The middle is what AI generates by default — a soft consensus of trends with no point of view. Refuse it. Pick one direction, state it explicitly at the top of the response, then execute every detail through that lens. + +If the brief says "playful," do not deliver "professional with a hint of warmth." Deliver playful. If it says "luxury minimal," do not add a single decorative flourish. Restraint is the work. + +### 3. Currency matters + +Material 3 from 2023 is not Material 3 Expressive from 2025. iOS 17 Materials are not Liquid Glass. Tailwind v3 patterns are not Tailwind v4. WinUI 2 is not WinUI 3 + WinAppSDK 1.8. Framer Motion is the legacy brand; the package is now `motion` from motion.dev. + +Generated UI from training data drift quietly toward the median version of each technology. Override that. State the version explicitly. Use the new APIs. The user did not install this skill to ship a 2023 app in 2026. + +## What "AI slop" actually means in 2026 + +The 2024 critique was about purple gradients and Inter. The 2026 critique is broader. Designers spot AI output by: + +- **Rhythm dies** — every section has identical `py-20` padding. Real design varies rhythm intentionally. +- **No risk** — every choice is the safe one. No type that surprises. No layout that breaks. +- **Component-shopping** — feels assembled from shadcn/ui defaults rather than designed +- **Confused dark mode** — slate-950 backgrounds with slate-300 text and one indigo accent (the "VS Code-as-product" aesthetic) +- **Centered everything** — no asymmetry, no diagonal, no overlap +- **Glass without intent** — glassmorphism applied because it's a vibe, not because it serves the content +- **Hero + 3-column features + CTA + footer** — the universal SaaS landing skeleton + +Output that avoids all of these will already place above 95% of AI-generated UI. The remaining 5% comes from picking a real direction and committing. + +## On platform-native vs cross-platform + +Cross-platform is a delivery strategy, not an aesthetic. A great product team picks one canonical platform, designs the product idiomatically for that platform, then translates to others — adjusting navigation, materials, motion, typography, and chrome to fit each host. + +A bad product team picks Flutter, designs once, and ships a Material-on-iOS hybrid that feels foreign on every platform. + +Idiom-design defaults to single-platform per skill, with an explicit `cross-platform-design` skill for the translation layer. This is the opposite of what v0/Lovable/Bolt/Subframe do. They all default to "web everywhere." This is wrong on Apple, wrong on Windows, wrong on Android. Defaulting to native is the wedge. + +## On taste + +Taste is not a magic property. Taste is reading the references — Awwwards SOTY 2025, Microsoft Fluent 2, Apple HIG, Material 3 Expressive — and absorbing the patterns until they become defaults. Every platform has a canonical reading list. Every reading list is finite. Read it. + +If a generation feels off, the fix is almost always: go look at how Things 3, Linear, Files, or Pixel Camera solve the same surface. Then do that. + +## Self-check before shipping + +Before delivering any generation, ask: +1. Did I pick a real direction and commit to it? +2. Does this fit alongside the platform's reference apps? +3. Did I avoid every item on the platform's ban list? +4. Is the typography distinctive (not Inter / Space Grotesk / system-ui)? +5. Does the motion feel intentional, not added? +6. If cross-platform: did I translate idiom, not pixels? + +If any answer is no, restart the choice that failed. Do not ship near-misses. diff --git a/plugins/f0d010c/stark/references/fluent-design.md b/plugins/f0d010c/stark/references/fluent-design.md new file mode 100644 index 000000000..2857d3950 --- /dev/null +++ b/plugins/f0d010c/stark/references/fluent-design.md @@ -0,0 +1,128 @@ +# Fluent Design 2 — Reference (Windows 11/12, May 2026) + +## Stack + +- **Windows App SDK 1.8** (stable, serviced through Mar 2026) +- **WinUI 3** (decoupled from OS release) +- **Windows App SDK 2.0** in preview, targeting .NET 10 +- **Native AOT** in preview + +Sources: +- https://learn.microsoft.com/windows/apps/winui/winui3 +- https://github.com/microsoft/WindowsAppSDK +- https://github.com/microsoft/microsoft-ui-xaml +- https://fluent2.microsoft.design + +## Materials + +### Mica +- Opaque, desktop-tinted backdrop +- Apply to **long-lived windows** (top-level) +- API: `` or `Window.SystemBackdrop = new MicaBackdrop()` +- Variants: `Mica` (default) and `Mica Alt` (stronger desktop tint, for tabbed apps like Terminal/Edge/Files) + +### Acrylic +- Translucent blur +- Apply ONLY to **transient surfaces**: flyouts, command bars, menus, tooltips +- Never on long-lived window backgrounds — use Mica there +- API: `` + +### Tonal elevation (replaces drop shadows) +- Surfaces gain prominence by shifting background brush, not adding shadow +- Use `LayerFillColorDefaultBrush`, `LayerOnAcrylicFillColorDefaultBrush`, `CardBackgroundFillColorDefaultBrush` +- All `ThemeResource` — automatic dark/light/high-contrast handling + +### Reveal +- **Deprecated** in Win11 styling +- Do not generate `RevealBackgroundBrush` or `RevealBorderBrush` in new code + +## Spacing & sizing + +- Base grid: **4 epx** +- Common increments: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64 +- Window corner radius: **8 epx** +- Control corner radius: **4 epx** +- Tight grid corner radius: **0 epx** +- Icon grid: 48×48 with 2px exterior radius, 1px interior + +## Typography + +- **Segoe UI Variable** (only correct face for new code) +- Variable axes: `wght` 100–700, optical-size axis (auto-adjusts to size) +- Never `Segoe UI` plain — that's the legacy face + +Type ramp (in epx): +- Caption: 12 / 16 line height, weight 400 +- Body: 14 / 20, weight 400 +- Body Strong: 14 / 20, weight 600 +- Body Large: 18 / 24, weight 400 +- Subtitle: 20 / 28, weight 600 +- Title: 28 / 36, weight 600 +- Title Large: 40 / 52, weight 600 +- Display: 68 / 92, weight 600 + +## Iconography + +- **Segoe Fluent Icons** font (1 epx monoline stroke) +- Sizes: 16, 20, 24, 32, 40, 48, 64 +- Cheatsheet: https://learn.microsoft.com/windows/apps/design/iconography/segoe-fluent-icons-font +- Never FontAwesome / Material Symbols / Lucide on Windows native + +## Title bar + +Every Win11 app **must** extend the client area: + +```csharp +// In App.xaml.cs or window code-behind +m_window.ExtendsContentIntoTitleBar = true; +m_window.SetTitleBar(AppTitleBar); + +// AppTitleBar should respect: +// - Caption buttons (min/max/close at right) +// - Snap Layouts hover (Win11: hover-on-maximize triggers snap groups) +// - Drag region for moving the window +``` + +Use `AppWindow.TitleBar` API for color customization. Never hand-roll caption buttons. + +## Canonical components + +| Need | Use | +|---|---| +| Top-level navigation | `NavigationView` (Left, LeftCompact, Top modes) | +| Settings rows | `SettingsCard`, `SettingsExpander` (CommunityToolkit.WinUI.Controls.SettingsControls) | +| Inline alert | `InfoBar` (Severity: Informational/Success/Warning/Error) | +| Coachmark | `TeachingTip` | +| Disclosure | `Expander` | +| Path / breadcrumb | `BreadcrumbBar` | +| Segmented toggle | `SelectorBar` (NEVER iOS-style sliding pill) | +| Picker | `DatePicker`, `TimePicker`, `PickerFlyout` | +| Command surface | `CommandBar`, `CommandBarFlyout` | + +Refer to **WinUI Gallery** for canonical control usage: https://github.com/microsoft/WinUI-Gallery — when generating, mirror its patterns exactly. + +## Architecture defaults + +- **CommunityToolkit.Mvvm** with `[ObservableProperty]`, `[RelayCommand]` source generators +- DI via `Microsoft.Extensions.Hosting` +- Settings persistence via `Windows.Storage.ApplicationData.Current.LocalSettings` or community Settings library +- Localization via `.resw` resource files + +## Win11/12 system integrations + +- **Snap Layouts** (Win11): hover on maximize button triggers; preserve via correct title bar implementation +- **Dynamic Lighting** (Win11 23H2+): `LampArray` API for RGB peripherals +- **Widgets** (Win11): `WidgetProvider` interface + `Widget` JSON schema +- **File Explorer context menu** (Win11): `IExplorerCommand` COM interface (sparse-package model in 11+) +- **Windows Hello / Passkeys**: `Microsoft.Web.WebAuthN` and platform credential APIs + +## Tokens + +- Token pipeline (W3C DTCG format): https://github.com/microsoft/fluentui-token-pipeline +- Reference token JSON shipped at `assets/tokens/fluent-2.json` + +## Win design downloads + +- Fluent 2 site: https://fluent2.microsoft.design +- Win design downloads (Figma, icons, Segoe): https://learn.microsoft.com/windows/apps/design/downloads +- Win11 Figma: https://www.figma.com/community/file/836828295772957889 diff --git a/plugins/f0d010c/stark/references/liquid-glass.md b/plugins/f0d010c/stark/references/liquid-glass.md new file mode 100644 index 000000000..fd9fdca4d --- /dev/null +++ b/plugins/f0d010c/stark/references/liquid-glass.md @@ -0,0 +1,102 @@ +# Liquid Glass — Apple's Unified Material (May 2026) + +Apple's design language since WWDC 2025. Unified across iOS 26, iPadOS 26, macOS 26 (Tahoe), watchOS 26, tvOS 26, visionOS 26. + +## Concept + +A digital meta-material that: +- **Refracts** underlying content (lensing effect) +- Adapts **multi-layer tint, shadow, dynamic-range** based on what's beneath +- Adapts **size-aware** — small surfaces get tighter blur, large surfaces get softer + +Lineage: Aqua (1999) → iOS 7 blurs (2013) → Dynamic Island (2022) → visionOS materials (2023) → Liquid Glass (2025). + +## Adoption checklist + +For an app to adopt Liquid Glass on iOS 26+: + +- [ ] **Build with Xcode 26 / Swift 6.2 / iOS 26 SDK** +- [ ] Toolbars use the system `.toolbar { ... }` modifier (auto-lifts to glass) +- [ ] Tab bars use `TabView` (not custom) — gain glass automatically +- [ ] Navigation uses `NavigationStack` / `NavigationSplitView` +- [ ] Buttons that should glass adopt `.buttonStyle(.glass)` +- [ ] Custom surfaces apply `.glassEffect()` modifier +- [ ] Multi-glass layouts wrap in `GlassEffectContainer` to coordinate refraction +- [ ] Scroll edges use `.scrollEdgeEffectStyle(.soft)` instead of hard chrome +- [ ] App icon rebuilt in **Icon Composer** (WWDC25 session 361) for Liquid Glass treatment +- [ ] Search bar uses `.searchable` (morphs into glass pill) + +## API surfaces + +```swift +// Single glass surface +Rectangle() + .glassEffect() + +// Coordinated glass (avoids overlapping refraction artifacts) +GlassEffectContainer { + HStack { + Capsule().glassEffect() + Capsule().glassEffect() + } +} + +// Glass button +Button("Sign In") { /* ... */ } + .buttonStyle(.glass) + +// Toolbar auto-glass +.toolbar { + ToolbarItem(placement: .primaryAction) { + Button("Save") { /* ... */ } + } +} +// → toolbar lifts to Liquid Glass automatically on iOS 26+ + +// Soft scroll edge instead of hard chrome +ScrollView { /* ... */ } + .scrollEdgeEffectStyle(.soft) + +// Glass-morphing search +.searchable(text: $query) +// → on iOS 26, search field morphs into a Liquid Glass pill when active +``` + +## When NOT to apply glass + +- On surfaces that should feel solid/grounded (e.g. error states, destructive confirmations) +- When the underlying content is already busy — glass refraction will compound noise +- On macOS sidebars (use `.background(.regularMaterial)` and `NSVisualEffectView` `.sidebar` instead) +- On surfaces smaller than ~44pt — glass needs space to breathe + +## Cross-platform adoption status (May 2026) + +| Stack | Liquid Glass support | +|---|---| +| **SwiftUI / UIKit native** | Full automatic adoption | +| **React Native** | Partial — `expo-glass-effect` and a few native modules expose `.glassEffect()`. Toolbar/tab integration weaker. | +| **Flutter Cupertino** | None — Flutter paints with Skia; can fake blur but not Liquid Glass refraction | +| **.NET MAUI iOS** | None | +| **React Native New Architecture + Fabric** | Better than old arch but still partial | + +If the user wants Liquid Glass and is asking about non-Swift: route to SwiftUI or warn explicitly that fidelity will be reduced. + +## Materials hierarchy on Apple (still relevant alongside Glass) + +For non-Liquid-Glass surfaces — still use materials: + +```swift +.background(.ultraThinMaterial) // most see-through +.background(.thinMaterial) +.background(.regularMaterial) // default sidebar / toolbar +.background(.thickMaterial) +.background(.ultraThickMaterial) // most opaque +``` + +On macOS, drop into `NSVisualEffectView` for specific contexts: `.sidebar`, `.headerView`, `.hudWindow`, `.underWindowBackground`, `.contentBackground`, `.titlebar`, `.menu`, `.popover`, `.windowBackground`. + +## Sources + +- WWDC 25 session 219: https://developer.apple.com/videos/play/wwdc2025/219/ +- Adopting Liquid Glass: https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass +- HIG materials: https://developer.apple.com/design/human-interface-guidelines/materials diff --git a/plugins/f0d010c/stark/references/material3-expressive.md b/plugins/f0d010c/stark/references/material3-expressive.md new file mode 100644 index 000000000..b908946fb --- /dev/null +++ b/plugins/f0d010c/stark/references/material3-expressive.md @@ -0,0 +1,212 @@ +# Material 3 Expressive — Reference (May 2026) + +Launched at Google I/O 2025. Default for Pixel 10 / Android 16 QPR1. Generated UI must adopt M3 Expressive — **not** baseline M3 from 2023. + +## What changed vs baseline M3 (2023) + +| Surface | Baseline M3 (2023) | M3 Expressive (2025+) | +|---|---|---| +| Motion | Easing curves (`FastOutSlowIn`) | Spring physics (`MotionScheme.expressive()`) | +| Shapes | 5 fixed corner radii | 35 morphable shapes (squircle, pill, cookie, clover, etc.) | +| Typography | Roboto Flex baseline ramp | Emphasized scale — bigger, heavier display | +| Buttons | One size | Small / Default / Large / Extra-large | +| Loading | Linear / circular indicators | Wavy progress (variable amplitude), contained loading indicator (cycles M3E shapes) | +| Floating actions | Standard FAB | Floating toolbar, FAB menu, button group, split button | +| Elevation | Tonal + drop shadow | **Tonal only** (drop shadow on M3E surfaces is wrong) | + +## Compose adoption + +```kotlin +// Gradle (BOM 2026.04.01) +implementation(platform("androidx.compose:compose-bom:2026.04.01")) +implementation("androidx.compose.material3:material3:1.4.0") + +// For shape-morphing chips: +implementation("androidx.compose.material3:material3:1.5.0-alpha18") +``` + +### Spring physics + +```kotlin +val motion = MotionScheme.expressive() + +// On any animation: +animateFloatAsState( + targetValue = if (selected) 1f else 0f, + animationSpec = motion.fastSpatialSpec() +) +``` + +Spec variants: `defaultSpatialSpec`, `fastSpatialSpec`, `slowSpatialSpec`, `defaultEffectsSpec` (for color/alpha), `fastEffectsSpec`, `slowEffectsSpec`. + +### Shape morphing + +```kotlin +import androidx.compose.material3.MaterialShapes + +// Available shapes (35 in M3E): +MaterialShapes.Cookie4Sided +MaterialShapes.Cookie6Sided +MaterialShapes.Cookie7Sided +MaterialShapes.Cookie9Sided +MaterialShapes.Cookie12Sided +MaterialShapes.Pill +MaterialShapes.Pixel +MaterialShapes.Boom +MaterialShapes.Bun +MaterialShapes.Burst +MaterialShapes.Clamshell +MaterialShapes.Clover4Leaf +MaterialShapes.Clover8Leaf +// ... and more + +// Apply: +Surface(shape = MaterialShapes.Cookie6Sided.toShape()) { ... } + +// Morph between shapes: +val morph = remember { Morph(MaterialShapes.Pill, MaterialShapes.Cookie6Sided) } +val progress = animateFloatAsState(if (pressed) 1f else 0f) +Box(modifier = Modifier.clip(morph.toPath(progress.value).asAndroidPath().toComposeShape())) +``` + +### Wavy progress + +```kotlin +LinearWavyProgressIndicator( + progress = { 0.7f }, + amplitude = WavyProgressIndicatorDefaults.indicatorAmplitude +) + +CircularWavyProgressIndicator( + progress = { 0.4f } +) +``` + +### Floating toolbar + +```kotlin +HorizontalFloatingToolbar( + expanded = true, + leadingContent = { /* ... */ }, + trailingContent = { /* ... */ }, + content = { + IconButton(onClick = {}) { Icon(Icons.Default.Edit, null) } + IconButton(onClick = {}) { Icon(Icons.Default.Share, null) } + } +) +``` + +### Button sizes + +```kotlin +Button(onClick = {}, contentPadding = ButtonDefaults.SmallContentPadding) { ... } +Button(onClick = {}) { ... } // default +Button(onClick = {}, contentPadding = ButtonDefaults.LargeContentPadding) { ... } +Button(onClick = {}, contentPadding = ButtonDefaults.ExtraLargeContentPadding) { ... } + +// Or use new component: +SplitButton( + onClick = {}, + onMenuClick = {}, + label = "Save", + menuContent = { /* ... */ } +) +``` + +## Dynamic color (Material You) + +```kotlin +val colorScheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { + if (darkTheme) dynamicDarkColorScheme(LocalContext.current) + else dynamicLightColorScheme(LocalContext.current) +} else { + if (darkTheme) darkColorScheme() else lightColorScheme() +} + +MaterialTheme(colorScheme = colorScheme, content = content) +``` + +## Adaptive layouts (mandatory on tablets/foldables) + +```kotlin +val adaptiveInfo = currentWindowAdaptiveInfo() + +NavigationSuiteScaffold( + navigationSuiteItems = { + items.forEach { item -> + item( + selected = item == selected, + onClick = { /* ... */ }, + icon = { Icon(item.icon, null) }, + label = { Text(item.label) } + ) + } + } +) { + // content — auto-adapts: NavigationBar (Compact), NavigationRail (Medium), NavigationDrawer (Expanded) +} +``` + +For list/detail: + +```kotlin +NavigableListDetailPaneScaffold( + navigator = scaffoldNavigator, + listPane = { /* ... */ }, + detailPane = { /* ... */ } +) +``` + +## Edge-to-edge (mandatory Android 16+) + +```kotlin +class MainActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + enableEdgeToEdge() + super.onCreate(savedInstanceState) + setContent { /* ... */ } + } +} + +// In Composables: +Scaffold( + contentWindowInsets = WindowInsets.systemBars +) { padding -> + Column(modifier = Modifier.padding(padding)) { /* ... */ } +} +``` + +`windowOptOutEdgeToEdgeEnforcement` is deprecated — do not use it. + +## Predictive back (mandatory Android 16+) + +```kotlin +PredictiveBackHandler(enabled = canGoBack) { backEvent -> + // backEvent: BackEventCompat with progress 0..1 + // animate based on progress + try { + backEvent.collect { event -> + animateProgress(event.progress) + } + // gesture confirmed + navigateBack() + } catch (e: CancellationException) { + // gesture canceled — animate back to rest + } +} +``` + +## Reference apps + +- **Pixel Launcher / Android 16 System UI** — shape morph + springs +- **Google Calendar** — floating toolbar + tonal surfaces +- **Fitbit (2025 redesign)** — `ContainedLoadingIndicator` cycling shapes +- **Pixel Camera 10.1** — wavy progress in capture +- **Androidify** sample — official Compose M3E reference: https://github.com/android/compose-samples/tree/main/Androidify + +## Sources + +- M3E deep dive: https://supercharge.design/blog/material-3-expressive +- Compose April '26 release: https://android-developers.googleblog.com/2026/04/jetpack-compose-april-2026-updates.html +- M3 site: https://m3.material.io +- Theme Builder: https://m3.material.io/theme-builder diff --git a/plugins/f0d010c/stark/references/ui-patterns/README.md b/plugins/f0d010c/stark/references/ui-patterns/README.md new file mode 100644 index 000000000..251efdb97 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/README.md @@ -0,0 +1,20 @@ +# UI pattern briefs + +These briefs define visual and interaction quality, not product flow. Use them after the UX decision brief, or directly when the user asks mainly for visual design. + +Good UI decisions are contextual: + +- A CRM dashboard should be dense, stable, and scannable. +- A marketing page should be memorable, directed, and conversion-aware. +- A native settings screen should feel boring in the right way. +- An editor should protect the canvas and make controls discoverable. + +Use these briefs to choose visual density, hierarchy, component grammar, motion budget, type, materials, imagery, and state treatment before writing code. + +Do not apply a visual style because it is fashionable. Pick it because it supports the product job, platform, and frequency of use. + +For dense products, also decide responsive containment before code: tables, nav rows, toolbars, inspectors, and canvases need bounded scroll, wrapping, or a breakpoint-specific replacement. The page itself should not drift sideways. + +When assets matter, add an asset plan before code. Choose whether the design needs icons, product screenshots, generated product mocks, typography, textures, reference UI patterns, brand assets, or GPT/Codex image generation. Pull only what supports the job and store attribution for external sources. + +When shipped references matter, add a reference extraction brief before code. Extract structure, interaction, state, recovery, responsive, and asset lessons from real products; do not copy their visuals. diff --git a/plugins/f0d010c/stark/references/ui-patterns/asset-selection.md b/plugins/f0d010c/stark/references/ui-patterns/asset-selection.md new file mode 100644 index 000000000..f1f4cfb59 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/asset-selection.md @@ -0,0 +1,83 @@ +# Asset selection + +Use this after the UI decision brief and before implementation when a design needs icons, screenshots, product previews, references, typography, textures, diagrams, or generated imagery. + +## Principle + +Assets are design evidence, not decoration. Each asset should help the user understand the product, trust the interface, or complete the job. + +## Ask before pulling + +- Do we need icons? +- Do we need real product screenshots? +- Do we need reference UI patterns? +- Do we need typography? +- Do we need brand assets? +- Do we need generated bitmap visuals because the agent stack supports image generation? + +If the answer is no, do not add the asset category. + +## Asset plan + +```md +Asset plan +- Needed assets: product UI mock, icons, texture, typeface +- Source: local Stark library, lucide, generated CSS/SVG mock, imagegen, external reference +- License risk: none / low / needs attribution / avoid +- Usage: hero product preview, warning states, workflow diagram +- Reference extraction: structure only, not copied visuals +- Bans: stock hero photos, random blobs, placeholder images +``` + +## Source choices + +| Need | Prefer | Avoid | +|---|---|---| +| Icons | platform icons, lucide, existing app icon set | mismatched icon packs, handmade generic SVG icons | +| Product proof | real app screenshots with permission, generated UI mock, code-rendered preview | placeholder images, blurred stock mockups | +| Fictional hero imagery | imagegen when available, custom CSS/SVG, product UI composition | random stock photos, abstract AI blobs | +| Typography | curated font pair, platform type, installed project fonts | default Inter/system-only unless native platform calls for it | +| UX references | proven flow screenshots or product references used as structure | copying exact visual style or brand assets | +| Texture/material | local generated texture, CSS noise/grid/material | decorative orbs, irrelevant atmospheric backgrounds | + +## Image generation + +When the user is using GPT/Codex and image generation is available, Stark may recommend generated bitmap assets for: + +- editorial hero imagery +- product concept scenes +- empty-state illustrations +- brand campaign visuals +- texture/material studies +- realistic product/device mockups + +Generated images must still fit the product job. Do not use imagegen to hide weak layout, missing state design, or generic copy. Prefer generated images when they add specific context that CSS/SVG would not communicate well. + +## Real-world UI references + +For flows such as onboarding, settings, permissions, checkout, dashboards, empty states, and mobile navigation, inspect 3-5 proven references when available. Read `reference-analysis.md` and extract: + +- information architecture +- hierarchy +- state coverage +- interaction pattern +- density and progressive disclosure +- recovery path + +Do not copy: + +- brand identity +- exact layout +- proprietary screenshots +- paid/reference-library assets into public output + +The rule is: extract structure, not visuals. + +## Security and privacy + +- Never include private/local screenshots unless the user explicitly allows it. +- No copyrighted brand assets in public output. +- No random stock filler when the product needs inspectable proof. +- Store source and attribution when using external assets. +- Prefer generated CSS/SVG/product mockups for fictional products. +- Reject assets that do not support the product job. diff --git a/plugins/f0d010c/stark/references/ui-patterns/cinematic-landing-system.md b/plugins/f0d010c/stark/references/ui-patterns/cinematic-landing-system.md new file mode 100644 index 000000000..3d1e40933 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/cinematic-landing-system.md @@ -0,0 +1,145 @@ +# Cinematic landing system + +Use this for landing pages that should feel like a polished campaign, launch page, editorial brand page, or high-craft interactive site. + +Do not use this as the default for dashboards, docs, checkout, forms, admin tools, or repeated-use product surfaces. + +## Surface modes + +Choose one mode before designing: + +| Mode | Use for | Page behavior | +|---|---|---| +| Campaign page | brand/product launch, event, food, fashion, culture, music, games | key art first, strong atmosphere, simple story, memorable motion | +| Editorial scroll story | museum, science, report, case study, manifesto | large type, measured sections, scroll-choreographed narrative | +| Product proof page | developer tools, security, AI, workflow products | product/key visual plus proof panels, fewer decorative scenes | +| Immersive brand page | luxury, hospitality, entertainment, studio, portfolio | material language, large imagery, signature transitions | + +If the page is mostly conversion or product education, use product proof. If the page is mostly mood and desire, use campaign or immersive brand. + +## Key art versus page design + +Do not confuse a strong hero visual with a finished page. + +First define the key art: + +- Subject: the product, object, character, artifact, specimen, machine, place, or visual metaphor. +- Material: glass, paper, metal, liquid, fabric, grain, light, shadow, scan, map, device, botanical, orbital, etc. +- Framing: centered object, oversized crop, diagonal object, floating plate, full-bleed scene, split text/object. +- Depth: foreground, midground, background, atmospheric layer. +- Reuse: how the same visual language returns later without repeating the hero. + +Then define the page system. If the request asks for something original, memorable, high-craft, or unusual, pair this with `creative-direction.md` and define the broader world, metaphor, tasteful risk, and restraints. + +- Grid: centered, asymmetric, hero+rail, editorial spread, pinned stage, gallery, index. +- Section rhythm: which sections are full-bleed, contained, narrow, split, or pinned. +- Typography: one headline system, one body system, one metadata system. +- Motion language: reveal, scrub, mask, parallax, carousel, route transition, or none. +- Restraint: one primary visual metaphor and one primary accent family. + +## Campaign page anatomy + +Use this sequence unless the user gives a stronger structure: + +1. Hero/key art: one oversized title or short phrase, one dominant visual, minimal supporting copy, one action or scroll cue. +2. Context/menu/index: introduce the world, collection, or offer with simple scannable content. +3. Proof or craft: explain why the object/service is special through process, detail, material, data, or artifact. +4. Collection/variations: carousel, gallery, cards, index list, or comparison with real names and attributes. +5. Human/trust/place: origin, makers, operators, customers, venue, map, schedule, or credibility. +6. Final brand close: large wordmark, repeated key art element, or simple CTA. + +Avoid stacking unrelated feature sections. Campaign pages should feel composed, not assembled. + +## Typography discipline + +Premium campaign pages usually use fewer type decisions: + +- One display face with a distinctive shape. +- One clean body face. +- One small metadata/caption treatment. +- Giant hero text must be manually line-broken. +- Do not let huge text clip accidentally on mobile. +- Use 2-3 headline sizes across the whole page, not a new size per section. +- Body copy should be short and purposeful. + +Good campaign copy is concrete: object names, materials, times, places, process details, sensory detail, risk, or transformation. + +Weak campaign copy is generic: "crafted for modern teams", "unlock your potential", "seamless experience", "powered by AI". + +## Section rhythm + +Use a deliberate rhythm instead of equal sections: + +| Section | Typical rhythm | +|---|---| +| Hero | full viewport, dominant title/visual | +| Context | shorter, text/list based | +| Craft/proof | full viewport or pinned | +| Collection | medium/tall, interactive or gallery | +| Trust/place | quieter, grounded | +| Final CTA | large, simple, memorable | + +Vary section height, width, and density. Avoid identical blocks from top to bottom. + +## Art direction constraints + +Before coding, state: + +```md +Art direction +- Visual metaphor: +- Key art: +- Material language: +- Typography system: +- Palette: +- Motion language: +- Repeated motif: +- Bans: +``` + +Rules: + +- One visual metaphor is enough. +- One material language is enough. +- One accent family is enough. +- Reuse motifs instead of inventing new decoration every section. +- If using images, they should look art-directed, not like random stock. +- If no real images are available, generate/code one strong visual system rather than many weak placeholders. + +## Motion choreography + +Cinematic pages may use expressive motion, but each motion needs a role: + +- Title reveal: introduces voice. +- Parallax: creates depth around key art. +- Pinned section: explains a transformation or sequence. +- Mask reveal: turns one image/state into another. +- Carousel: lets the user explore a collection. +- Scroll-synced video: shows process over time. + +Use 2-4 signature moments total. If every section has its own unrelated trick, the page feels noisy. + +## Reference extraction + +When using a high-craft reference site, extract: + +- first viewport composition +- key art framing +- type scale and line breaks +- section sequence +- asset reuse +- motion pacing +- mobile simplification + +Do not copy subject, exact layout, assets, copy, brand colors, or distinctive trade dress. + +## Common failure modes + +- Cool hero visual, weak rest of page. +- Each section has a different visual idea. +- Typography is large but not composed. +- Text clips on mobile. +- GSAP is used for movement but not storytelling. +- Generated assets are atmospheric but not tied to the subject. +- Page feels like a dashboard wearing a marketing skin. +- Page has no final memorable close. diff --git a/plugins/f0d010c/stark/references/ui-patterns/creative-direction.md b/plugins/f0d010c/stark/references/ui-patterns/creative-direction.md new file mode 100644 index 000000000..d6ff09a08 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/creative-direction.md @@ -0,0 +1,94 @@ +# Creative direction + +Use this before implementation when the user asks for a polished, original, non-generic, memorable, weird, high-craft, campaign, product, or "best-looking" interface. + +Creativity is not random decoration. It is a specific world, a few strong constraints, and one tasteful risk held consistently across the interface. + +## Creative direction brief + +Before coding, produce this: + +```md +Creative direction brief +- Subject: +- Audience: +- World: +- Mood: +- Visual metaphor: +- Material language: +- Typography personality: +- Layout grammar: +- Motion voice: +- Repeated motif: +- Forbidden defaults: +- Tasteful risk: +- Restraints: +``` + +## How to fill it + +- Subject: the real thing being sold, operated, inspected, tracked, learned, or enjoyed. +- Audience: who uses it and how sophisticated their taste/workflow is. +- World: the place or system the product feels like it belongs to. +- Mood: 2-3 adjectives with tension, not a single generic word. +- Visual metaphor: one concrete metaphor that can shape layout, imagery, and motion. +- Material language: glass, paper, metal, ink, radar, specimen, terminal, botanical, textile, industrial label, map, light table, etc. +- Typography personality: editorial, mechanical, luxury, civic, scientific, playful, archival, terminal, museum label, etc. +- Layout grammar: stage, rail, index, cockpit, spread, specimen tray, command deck, calendar, map, stack, timeline. +- Motion voice: snap, drift, reveal, scrub, mechanical, cinematic, quiet, none. +- Repeated motif: one visual element that returns in multiple sections. +- Forbidden defaults: the obvious template this must not become. +- Tasteful risk: one deliberate unusual move. +- Restraints: the rules that keep the risk from turning messy. + +## Tasteful risk examples + +Pick one, or invent one that fits the subject: + +- Hero headline is partly hidden behind the key object. +- Navigation is vertical like a museum label. +- Primary CTA lives inside a control strip instead of a centered hero row. +- Feature sections are specimen labels, not cards. +- Product proof is shown as a run log, receipt, blueprint, or inspection sheet. +- Section titles behave like chapter markers. +- The page opens with a short ritual: calibration, scan, pour, boot, focus, develop, fold. +- A single object recurs at different scales through the page. +- The main grid is intentionally off-center with a stable side rail. +- The final CTA is a large closing mark instead of another button band. + +## Constraints create originality + +Use constraints before adding more ideas: + +- one visual metaphor +- one material language +- one accent family +- one display type personality +- one body/caption system +- one repeated motif +- two to four signature interactions +- no unrelated decoration +- no generic feature-card grid unless comparison is truly needed + +## Reference use + +When using a reference, extract structure only: + +- What is the first visual decision? +- What does the page repeat? +- How does the reference create contrast between sections? +- What is the motion doing for meaning? +- Where does it intentionally break symmetry? +- What does it refuse to include? + +Do not copy the subject, assets, copy, colors, exact layout, brand identity, or trade dress. + +## Common failures + +- "Creative" means many unrelated effects. +- The hero is interesting but the rest is generic. +- Every section has a new metaphor. +- The tasteful risk appears once and disappears. +- Motion is added before the visual system exists. +- The page is weird but does not communicate the product job. +- The design copies a reference instead of extracting structure. diff --git a/plugins/f0d010c/stark/references/ui-patterns/interaction-techniques.md b/plugins/f0d010c/stark/references/ui-patterns/interaction-techniques.md new file mode 100644 index 000000000..ac7e57c32 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/interaction-techniques.md @@ -0,0 +1,196 @@ +# Interaction techniques + +Use this before implementation when a web design needs animation, scrolling, route transitions, command surfaces, split panes, or advanced interaction. This is product guidance, not a learning roadmap. + +## Principle + +Interaction should communicate one of four things: + +- Hierarchy: what matters now. +- Continuity: what changed and where it came from. +- Progress: what the system is doing. +- Control: how the user can act faster or recover. + +If a motion or scrolling idea does not support one of those jobs, do not add it. + +## Technique decision matrix + +| Technique | Use when | Strong surfaces | Avoid when | +|---|---|---|---| +| CSS transitions | Simple hover, focus, disclosure, tab, button, or status changes | all surfaces | sequencing multiple dependent elements | +| CSS keyframes | Small repeating or entrance animations | loaders, subtle ambience, status pulses | high-frequency dashboards with many animated rows | +| Motion for React / motion.dev | React component motion, layout transitions, modals, sheets, command palettes, route/detail continuity | apps, dashboards, docs, product-led sites | complex pinned scroll stories or SVG choreography | +| GSAP ScrollTrigger | Complex timeline, pinned scroll, scrubbed hero, character/SVG choreography | launch pages, editorial product stories, portfolios | dashboards, docs, forms, checkout, admin tools | +| Native scroll-driven CSS | Lightweight scroll progress, reveal-on-view, subtle section effects | editorial pages, docs progress, simple landing pages | critical flows without fallback, nested scroll containers | +| Lenis smooth scroll | Branded scroll feel as part of an immersive page | editorial, type-led, portfolio, campaign pages | dashboards, docs, forms, editors, admin tools | +| View Transitions API | Shared-element route/detail transitions | galleries, docs, app shells, product catalogs | hiding loading/error/permission changes | +| Command palette | Fast access to actions and navigation | devtools, docs, editors, dense SaaS | simple marketing pages | +| Inspector split pane | Keep list context while inspecting detail | dashboards, queues, audits, CRM, CI/deploys | one-off forms or simple landing pages | +| Timeline/run replay | Explain long-running or multi-step work | AI agents, CI, deploys, imports, automations | static marketing proof without process | +| Before/after slider | Compare transformation | redesigns, migrations, optimization, image/product changes | abstract value claims without visible delta | +| Keyboard shortcut overlay | Teach expert paths | editors, dashboards, command surfaces | first-run onboarding before basic actions are clear | + +## Surface defaults + +### Marketing / brand page + +Default: one signature moment plus restrained baseline. + +Good: + +- hero reveal +- annotated product proof +- one pinned product story +- before/after comparison +- parallax or scroll reveal when it supports the narrative + +Avoid: + +- every section animating the same way +- Lenis plus parallax plus custom cursor plus pinned scroll by default +- motion that delays the conversion action + +### SaaS dashboard / admin / CRM + +Default: subtle, fast, stable. + +Good: + +- split pane +- command palette +- inline loading +- row expansion +- saved-view transition +- skeletons +- keyboard shortcut overlay + +Avoid: + +- smooth scroll +- scroll hijacking +- hover floating on every card +- animated counters that distract from real status +- pinned marketing story sections inside work surfaces + +### Docs / API reference + +Default: navigational clarity. + +Good: + +- sticky nav +- active section marker +- search or command palette +- copy button feedback +- code tab transitions +- lightweight scroll progress + +Avoid: + +- custom cursor +- parallax +- slow page-load curtains +- animation that makes code harder to copy + +### Checkout / pricing / upgrade + +Default: reassuring and direct. + +Good: + +- plan selection feedback +- inline validation +- price recalculation +- comparison table highlighting +- success confirmation + +Avoid: + +- playful motion near payment risk +- delayed buttons +- scroll effects that hide price, trial, cancellation, or risk details + +### Editor / canvas / builder + +Default: functional. + +Good: + +- selection feedback +- drag/resize affordances +- inspector transitions +- command palette +- undo/redo confirmation + +Avoid: + +- panel motion that shifts the canvas +- animated controls that move away from the cursor +- scroll tricks inside the work area + +### Agent run / tool execution + +Default: informative. + +Good: + +- plan preview +- progress timeline +- logs +- artifact arrival +- retry/cancel/resume controls +- stale or blocked state + +Avoid: + +- spinner-only loading +- celebratory animation before artifacts are available +- hiding tool calls or error details behind decorative cards + +## Library selection rules + +- Start with CSS for simple transitions. +- Use Motion for React (motion.dev) when component state, layout continuity, command palettes, route/detail transitions, sheets, or modal animation matters. +- Use GSAP only when there is a clear timeline or scroll-story requirement. +- Use Lenis only when scroll feel is part of the brand surface. +- Use native scroll-driven CSS only when the effect is progressive enhancement or the target browser support is acceptable. +- Use no animation when stability, reading, copying, comparing, or recovering matters more. + +## Interaction budget + +Choose one budget before implementation: + +| Budget | Limit | Good for | +|---|---|---| +| none | no decorative motion; state changes only | docs, forms, admin, accessibility-sensitive surfaces | +| subtle | 1-3 small transitions, under 200ms | dashboards, settings, checkout, editors | +| functional | 2-4 interaction behaviors tied to workflow | devtools, agent runs, split-pane apps | +| signature | 1 hero motion + 2-3 supporting moments | product pages, launch pages | +| expressive | 2-4 coordinated sequences, tested carefully | campaigns, portfolios, type-led editorial | + +Do not exceed the budget unless the user explicitly asks for an expressive showcase. + +## Output expectation + +When interaction is non-trivial, include this in the UI decision brief: + +```md +Interaction decision +- Budget: none / subtle / functional / signature / expressive +- Techniques: ... +- Library: CSS / Motion / GSAP / native scroll CSS / Lenis / none +- Why this fits: ... +- Reduced-motion behavior: ... +- What was rejected: ... +``` + +## Red flags + +- GSAP added to a dashboard only for card reveal. +- Lenis added to docs or admin UI. +- Scroll hijacking on checkout. +- Custom cursor on dense forms. +- Motion that moves controls during pointer interaction. +- No `prefers-reduced-motion` behavior. +- Animation hiding loading, error, permission, or payment details. +- Five or more unrelated motion tricks on one page. diff --git a/plugins/f0d010c/stark/references/ui-patterns/motion-budget.md b/plugins/f0d010c/stark/references/ui-patterns/motion-budget.md new file mode 100644 index 000000000..f12bab501 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/motion-budget.md @@ -0,0 +1,58 @@ +# Motion budget + +Motion should explain state, continuity, or brand. It should not decorate every interaction. + +| Product type | Motion budget | Good motion | Avoid | +|---|---|---|---| +| Operational dashboard | subtle | row expansion, filter transition, inline loading | scroll theatrics, card float on every hover | +| Marketing page | signature | hero reveal, scroll-tied proof, product demo transitions | every section animating the same way | +| Native settings | minimal | system transitions, disclosure, focus movement | custom easing that fights OS expectations | +| Editor/canvas | functional | selection, drag, resize, undo feedback | panel motion that shifts the canvas | +| Checkout/upgrade | reassuring | plan selection, price update, success confirmation | playful delays near payment | +| Agent/tool run | informative | progress, step changes, artifact arrival | spinner-only indefinite waiting | + +Always respect reduced motion: + +- Disable parallax and scroll-tied motion. +- Keep opacity/position transitions short. +- Preserve information changes without animation dependency. + +## Budget levels + +Choose the motion budget before choosing a library: + +| Budget | Max motion surface | Use for | Reject | +|---|---|---|---| +| none | state changes only | docs, legal, simple forms, high-risk admin | decorative reveal, parallax, custom cursor | +| subtle | 1-3 short transitions | dashboards, settings, checkout, native-like apps | pinned scroll, smooth scroll, repeated card float | +| functional | 2-4 workflow interactions | command palettes, split panes, editors, agent runs | brand-only motion that slows the task | +| signature | 1 hero moment + 2-3 support moments | product pages, launches, case studies | every section using a different trick | +| expressive | 2-4 coordinated sequences | campaign, portfolio, type-led editorial | risky checkout/admin/docs flows | + +If the product is used daily, the default budget is subtle or functional. If the product is a one-off brand surface, the default can be signature. + +## Library fit + +| Choice | Pick it for | Do not pick it for | +|---|---|---| +| CSS transitions | hover, focus, tabs, disclosure, feedback | complex sequencing | +| CSS keyframes | small loops, loaders, ambient texture | large lists or dense dashboards | +| Motion for React | component state, layout continuity, modals, sheets, route/detail transitions | complex pinned scroll choreography | +| GSAP ScrollTrigger | scrubbed timelines, pinned product stories, SVG/text choreography | ordinary SaaS dashboards, docs, checkout | +| Native scroll-driven CSS | progress, reveal-on-view, progressive enhancement | critical interactions without fallback | +| Lenis | branded editorial scroll feel | dashboards, docs, forms, editors, admin | +| none | stability, speed, reading, copying, comparing, recovery | brand campaign surfaces | + +## Required output + +For non-trivial interaction, add: + +```md +Interaction decision +- Budget: ... +- Techniques: ... +- Library: ... +- Why this fits: ... +- Reduced-motion behavior: ... +- Rejected: ... +``` diff --git a/plugins/f0d010c/stark/references/ui-patterns/product-quality-bar.md b/plugins/f0d010c/stark/references/ui-patterns/product-quality-bar.md new file mode 100644 index 000000000..0d0ebbba1 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/product-quality-bar.md @@ -0,0 +1,103 @@ +# Product quality bar + +Use this before implementation when Stark is asked to make a UI "better", "polished", "less generic", or ready to show publicly. + +The goal is not more decoration. The goal is a surface that looks like it belongs to a specific product with a specific job. + +## The five checks + +### 1. Specific job + +The first viewport or first screen must answer: + +- What is this product for? +- What object is the user working on? +- What decision or action matters next? + +Weak signal: generic cards, generic metrics, generic "manage everything" copy. + +Strong signal: domain-specific object names, real statuses, realistic records, clear next action, visible consequence. + +### 2. Proof over claims + +Prefer proof surfaces to marketing claims: + +- Product screenshot or generated product mock +- Live-looking data table, inspector, run timeline, command palette, settings matrix +- Before/after comparison +- Annotated workflow +- Audit trail, permission state, cost/risk summary + +If a section says "fast", show what became faster. If it says "secure", show permission, audit, or policy behavior. If it says "AI", show plan, progress, artifacts, retry, and stop controls. + +### 3. Complete states + +At minimum, define: + +- Empty +- Loading +- Partial +- Error +- Permission blocked +- Success +- Long-running or stale state when relevant + +A beautiful happy path is not enough for a product UI. + +### 4. Scan speed + +For repeated-use products, users should be able to scan: + +- Priority +- Status +- Owner/source +- Timestamp +- Next action +- Risk/cost + +Use dense lists, tables, split panes, saved views, command palettes, and keyboard overlays when they support repeated work. + +### 5. Memorable restraint + +For marketing and brand surfaces, one memorable move is better than five decorative tricks. + +Pick one anchor: + +- Unusual typography +- Product proof hero +- Editorial grid +- Motion transition +- Material texture +- Interactive comparison + +Everything else should support that anchor. + +## Rewrite rule + +If a design could be reused by a CRM, AI SaaS, finance dashboard, and developer tool by changing only the logo, it is not specific enough. + +Before coding, replace generic elements with product-specific ones: + +| Generic | Stronger | +|---|---| +| "Dashboard" | "Failed deploy triage" | +| "Customers" | "Accounts at renewal risk" | +| "Activity" | "Policy changes requiring approval" | +| "AI assistant" | "Run plan, tool calls, artifacts, retry path" | +| "Analytics" | "Conversion drop by step, segment, and recovery action" | +| "Settings" | "Permissions, billing, notifications, data retention" | + +## Output expectation + +When Stark builds or audits UI, include a short quality-bar note: + +```md +Quality bar +- Specific job: ... +- Proof surface: ... +- Required states: ... +- Scan-speed decision: ... +- Memorable anchor: ... +``` + +Keep it short. The note is there to guide code, not to become product strategy theater. diff --git a/plugins/f0d010c/stark/references/ui-patterns/reference-analysis.md b/plugins/f0d010c/stark/references/ui-patterns/reference-analysis.md new file mode 100644 index 000000000..edc4d87c4 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/reference-analysis.md @@ -0,0 +1,75 @@ +# Reference analysis + +Use this when Stark inspects shipped products, Mobbin/Figma/reference screenshots, product docs, or public app examples before designing. + +## Principle + +References are evidence of decisions, not source material to clone. Extract the structure behind the design, then adapt it to the user's product, platform, constraints, and visual direction. + +## Extract + +For every reference, capture: + +- Product context: category, user mode, frequency, risk, and platform. +- User job: what the screen helps the user finish. +- Information architecture: primary object, navigation model, grouping, and depth. +- Hierarchy: primary visual, primary action, secondary actions, status, and metadata. +- Density: sparse, balanced, dense, operational, or expert. +- State coverage: empty, loading, partial, permission, error, success, stale, long-running. +- Interaction model: mouse, keyboard, command palette, drag/drop, bulk actions, inline edit, undo, drilldown, inspector. +- Recovery path: where the user goes when access, payment, deployment, sync, or validation fails. +- Responsive behavior: collapse, stack, split pane, drawer, horizontal containment, or mobile-specific pattern. +- Asset usage: icons, product screenshots, generated visuals, diagrams, photography, data viz, typography, texture. +- Trust signals: source, timestamp, permissions, audit trail, cost, ownership, and irreversible action warnings. + +For cinematic landing references, also capture: + +- First viewport composition: title placement, key art placement, nav weight, CTA placement. +- Key art system: subject, material, crop, lighting, depth, and how it repeats. +- Typography composition: display face, line breaks, scale jumps, metadata treatment. +- Section rhythm: full-bleed, contained, pinned, gallery, index, quiet sections. +- Motion pacing: title reveal, parallax, mask, pinned sequence, carousel, video scrub, final close. +- Mobile simplification: what gets removed, stacked, or reframed. + +## Do not copy + +- Brand identity, exact layout, proprietary screenshots, distinctive illustrations, copy, or trade dress. +- Paid reference-library assets into public output. +- Platform-specific idioms onto the wrong platform. +- A pattern just because it appears in a respected product. + +## Reference comparison + +Inspect 3-5 references when possible. Use this table: + +| Reference | Job | IA pattern | Interaction | State lesson | Responsive lesson | Keep | Avoid | +|---|---|---|---|---|---|---|---| +| Product / screen | ... | ... | ... | ... | ... | structural decision | visual identity | + +Then write: + +```md +Reference extraction brief +- Pattern chosen: ... +- Why it fits this user's job: ... +- Structural decisions to borrow: ... +- Decisions to reject: ... +- State/responsive requirements: ... +- Asset/source constraints: ... +``` + +## Source quality + +- Strong: official product docs, live app inspection, first-party screenshots, user-tested design systems, current platform guidelines. +- Useful but limited: marketing screenshots, blog breakdowns, public videos, Mobbin-style reference libraries. +- Weak: Dribbble shots, unlabeled screenshots, screenshots without workflow context, trend galleries. + +## Shipped-product heuristics + +- A shipped screen proves a real product team made a decision. It does not prove the decision is optimal. +- Repeated patterns across several products are stronger evidence than one beautiful screen. +- Workflow screens teach more than hero pages. +- Error, permission, empty, and settings screens teach more about product maturity than polished marketing screenshots. +- The more risky the action, the closer cost, permission, undo, and recovery copy should be to the action. +- Expert tools should expose shortcuts and command surfaces without hiding primary mouse paths. +- High-craft landing pages usually look clean because assets, type, palette, and section rhythm are constrained together. Motion reveals that system; it does not replace the system. diff --git a/plugins/f0d010c/stark/references/ui-patterns/responsive-containment.md b/plugins/f0d010c/stark/references/ui-patterns/responsive-containment.md new file mode 100644 index 000000000..9deefc403 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/responsive-containment.md @@ -0,0 +1,34 @@ +# Responsive containment + +Use this before shipping dense web apps, dashboards, editors, admin tools, tables, boards, and toolbars. + +## Rule + +Every surface must fit the viewport, but every data region does not have to collapse into cards. Dense tools can preserve tables, tab rows, filter chips, timelines, and inspectors when the overflow is intentionally contained. + +## Required decisions + +- Navigation: wrap, collapse, or make the nav row horizontally scrollable inside its own region. +- Tables: choose one of three patterns per breakpoint: contained horizontal scroll, priority-column list, or master/detail cards. +- Toolbars: keep primary actions visible; move rare filters into menus, drawers, or secondary rows. +- Inspectors: stack below the selected item on narrow screens, or use a sheet/drawer when the item must stay visible. +- Long labels: set wrapping or truncation rules before implementation. + +## Acceptable overflow + +- A table inside a clearly bounded scroll container with visible affordance. +- A chip/filter row that scrolls independently. +- A canvas/editor area that pans by design. + +## Unacceptable overflow + +- The whole page scrolls sideways because a nav, table, toolbar, code block, or inspector is wider than the viewport. +- Important actions are only reachable by accidental horizontal page scroll. +- A desktop dashboard is simply squeezed into a phone without changing navigation, table behavior, or detail panes. + +## Implementation checks + +- Test at 390px, 768px, and desktop width. +- Run a horizontal-overflow check on visible elements. +- Verify focus states remain reachable inside scroll containers. +- Prefer `overflow-x: auto` on the specific region, not `overflow-x: hidden` on the page as a cover-up. diff --git a/plugins/f0d010c/stark/references/ui-patterns/surface-taxonomy.md b/plugins/f0d010c/stark/references/ui-patterns/surface-taxonomy.md new file mode 100644 index 000000000..108945816 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/surface-taxonomy.md @@ -0,0 +1,15 @@ +# Surface taxonomy + +Choose the surface type before visual execution. + +| Surface | UI priority | Best visual grammar | Common failure | +|---|---|---|---| +| Marketing page | memory, credibility, conversion | editorial sections, strong hero, real product proof, directed motion | generic SaaS hero + 3 cards | +| SaaS dashboard | scan speed, comparison, repeated action | operational thesis, tables/lists, saved filters, priority stack, master/detail, contained overflow | decorative cards replacing useful density, generic CRM furniture, page-level horizontal scroll | +| Native settings | trust, predictability, accessibility | grouped settings, inline validation, platform controls | over-branded controls that feel non-native | +| Editor/canvas | artifact focus, tool discovery, reversibility | canvas, toolbars, inspector, command palette, undo/redo | panels fighting the canvas | +| Mobile task flow | thumb reach, clarity, progressive disclosure | native nav, sheets, sticky action, short forms | web layout squeezed into phone | +| Checkout/upgrade | trust, cost clarity, decision confidence | comparison, transparent CTA, risk copy near action | hidden renewal/cancellation details | +| Agent/tool run | trust in work, traceability, recovery | plan, progress, log, artifacts, retry/stop | invisible "working..." state | + +Use this taxonomy in both web and native skills. It decides density and component grammar before aesthetics. diff --git a/plugins/f0d010c/stark/references/ui-patterns/ui-audit-rubric.md b/plugins/f0d010c/stark/references/ui-patterns/ui-audit-rubric.md new file mode 100644 index 000000000..74bd5efb6 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/ui-audit-rubric.md @@ -0,0 +1,33 @@ +# UI audit rubric + +Use this before final delivery or when auditing a screen. + +## High severity + +- Primary action is unclear or visually buried. +- Surface type is wrong: marketing composition used for an operations tool, or dense admin UI used for conversion. +- Dashboard or admin UI has no operational thesis and could belong to any product after replacing labels. +- Native platform idioms are violated: wrong icons, type, navigation, materials, or controls. +- Text overlaps, overflows, or cannot fit in controls at common viewport sizes. +- Page-level horizontal overflow appears on mobile or tablet because a nav, table, toolbar, inspector, or code block is not contained. +- Loading/error/permission/success visuals are missing for a real workflow. +- Visual asset is fake, placeholder, blurred beyond usefulness, or unrelated. + +## Medium severity + +- Too many competing accents or hierarchy levels. +- Repeated cards where tables/lists/panes are needed. +- Dense tables or filter rows use accidental page overflow instead of a bounded scroll region or responsive replacement. +- Motion is decorative and slows repeated use. +- Component spacing is one-note and makes scanning harder. +- Empty state explains features instead of the next action. +- Icons are generic, mismatched, or manually drawn when a platform icon exists. + +## Low severity + +- Copy can be more concrete. +- Minor color/token drift. +- Hover/focus states are present but bland. +- Section rhythm could be more varied. + +Fix high severity issues before polish. A beautiful screen with the wrong surface type is still wrong. diff --git a/plugins/f0d010c/stark/references/ui-patterns/ui-decision-brief.md b/plugins/f0d010c/stark/references/ui-patterns/ui-decision-brief.md new file mode 100644 index 000000000..09eb87828 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/ui-decision-brief.md @@ -0,0 +1,46 @@ +# UI decision brief + +Produce this after the UX decision brief and before implementation. Keep it compact enough to guide code generation. + +```md +UI decision brief +- Surface type: marketing / dashboard / native settings / editor / mobile flow / checkout / agent run +- Platform idiom: web / Windows / Apple / Android / cross-platform translation +- Product thesis: the specific job, risk, queue, artifact, or decision this surface exists for +- Visual direction: ... +- Creative direction: see `creative-direction.md` brief, including world, mood, visual metaphor, material language, typography personality, layout grammar, motion voice, repeated motif, forbidden defaults, tasteful risk, and restraints +- Density: sparse / balanced / dense / operational +- Hierarchy: primary visual, primary action, secondary surfaces +- Component grammar: cards, tables, panes, toolbars, sheets, tabs, forms, command surface +- Typography: system/native or chosen custom pair, scale, emphasis rule +- Color/materials: background, surfaces, accent, semantic states +- Motion budget: none / subtle / signature / expressive, plus reduced-motion behavior +- Implementation track: static / Vite + React / Next / Astro / other, plus dependency risk notes +- Responsive containment: nav, table/list, toolbar, inspector, and long-label behavior +- Cinematic system: campaign / editorial scroll story / product proof / immersive brand, if applicable +- Key art: subject, material, framing, depth, and reuse plan +- Art direction: visual metaphor, typography system, palette, motion language, repeated motif +- Page rhythm: hero, context, proof/craft, collection, trust/place, final close +- Asset plan: icons, screenshots, generated UI mock, imagegen, typography, references, attribution +- Reference extraction: shipped references used, structural lessons, rejected visual/copy elements +- Assets: real product media, generated illustration, icons, screenshots, data visualizations, none +- State visuals: empty, loading, error, permission, success, long-running +- Tasteful risk: one deliberate unusual choice and the restraints that keep it coherent +- Bans: ... +``` + +This brief prevents the common failure where the agent picks decent components but no coherent visual system. + +## Rules + +- Dense work tools need stable layout more than animation. +- Dense regions need intentional containment: table scroll, priority-column list, sheet/drawer, or breakpoint-specific replacement. +- Dashboards need a product-specific operational thesis before visual polish; avoid generic CRM/admin furniture with interchangeable labels. +- Assets must prove the product job or strengthen the visual direction; reject decorative filler. +- Marketing pages need a memorable first viewport and one clear conversion path. +- Creative pages need one concrete world and one tasteful risk, not many unrelated effects. +- Cinematic landing pages need one key-art system and page rhythm before motion decisions. +- Web stacks must match the product surface: React is useful for stateful, componentized, animated work, but static pages should stay simpler when possible. +- Native apps need platform materials, type, icons, spacing, and controls before custom flair. +- Editor tools need canvas dominance and control stability. +- If UX and UI conflict, preserve the user's job and recovery path first. diff --git a/plugins/f0d010c/stark/references/ui-patterns/visual-hierarchy.md b/plugins/f0d010c/stark/references/ui-patterns/visual-hierarchy.md new file mode 100644 index 000000000..4f9f083ca --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/visual-hierarchy.md @@ -0,0 +1,42 @@ +# Visual hierarchy rules + +Use this to prevent visually polished but confusing screens. + +## Primary visual + +Every screen needs one dominant visual anchor: + +- marketing: product, offer, or proof +- dashboard: priority metric/list/alert stack +- editor: canvas/artifact +- settings: selected group and current setting +- checkout: selected plan/total/action +- agent run: current step/progress/artifacts + +If everything is equally styled, nothing is important. + +For cinematic landing pages, the primary visual is usually key art: a dominant object, scene, product proof, specimen, machine, device, place, or metaphor. It must carry the first viewport and return later as a motif. Do not make a cool hero image and then abandon its visual language for unrelated cards. + +## Action hierarchy + +- One primary action per surface. +- Secondary actions must be visually secondary, not just placed later. +- Destructive actions need distance, confirmation, or undo. +- Repeated actions should be closer and faster than rare actions. + +## Layout rhythm + +- Use spacing changes to show grouping, not just decoration. +- Avoid identical section padding across the whole page. +- Align text, controls, and data to a deliberate grid. +- Stable dimensions matter for tables, toolbars, boards, cards, and navigation. +- On narrow screens, preserve the hierarchy by containing dense regions or changing their presentation; do not let the whole page become the scroll container for one oversized element. +- Campaign pages need a composed sequence, not interchangeable sections: hero/key art, context, craft/proof, collection, trust/place, final close. +- Huge display typography must be deliberately line-broken and tested against narrow widths; accidental clipping is a layout failure, not an aesthetic. + +## State hierarchy + +- Empty states should tell how data arrives. +- Loading states should preserve layout shape. +- Errors should appear near the failed thing. +- Success should point to the next useful action. diff --git a/plugins/f0d010c/stark/references/ui-patterns/web-implementation-tracks.md b/plugins/f0d010c/stark/references/ui-patterns/web-implementation-tracks.md new file mode 100644 index 000000000..c2c226795 --- /dev/null +++ b/plugins/f0d010c/stark/references/ui-patterns/web-implementation-tracks.md @@ -0,0 +1,74 @@ +# Web implementation tracks + +Use this before choosing a frontend stack. Pick the smallest stack that can execute the design well. + +Do not default every page to React. Do not avoid React when the interaction model clearly needs component state, animation orchestration, routing, or reusable product surfaces. + +## Track choices + +| Track | Use when | Avoid when | +|---|---|---| +| Static HTML/CSS/JS | simple landing page, docs fragment, one-off prototype, small animation, no persistent state | complex interactive UI, many reusable sections, rich animation state | +| Vite + React | advanced landing page, animated campaign, dashboard, command palette, filters, inspectors, app shell, stateful demo | content-heavy SEO site that needs server/rendering decisions | +| Next.js | marketing + app hybrid, SEO, routing, server data, auth, docs/product pages at scale | static one-pager or local prototype where framework weight adds little | +| Astro | content/editorial site, docs, mostly static pages with islands of interactivity | dense app UI, complex client-side state everywhere | +| SvelteKit, Solid, or Qwik | user explicitly asks, existing project uses it, or performance/interaction model fits | when the agent would choose it just to be novel | + +## React is worth it when + +- Components repeat across sections or screens. +- UI state changes frequently: filters, selection, tabs, sheets, command palettes, inspectors, forms. +- Animation depends on component state, layout continuity, or route/detail transitions. +- The page includes interactive product demos or simulated app UI. +- The work will grow into an app, dashboard, or reusable design system. +- Libraries such as Motion/motion.dev, GSAP React integration, React Three Fiber, shadcn, or TanStack are central to the plan. + +## React is not worth it when + +- The page is mostly static copy and imagery. +- The only interaction is hover, focus, disclosure, or simple scroll reveal. +- A plain CSS/JS solution is clearer, faster, and easier to audit. +- The design is a small embed or isolated static artifact. +- Adding npm dependencies increases risk without buying real behavior. + +## Stack decision brief + +Before coding a web surface, state: + +```md +Implementation track +- Track: static / Vite + React / Next / Astro / other +- Why this track fits: +- Why the simpler track was rejected: +- Required dependencies: +- Dependency risk notes: +- Lockfile/audit plan: +``` + +## Dependency safety + +When installing dependencies, especially during active npm supply-chain incidents: + +- Prefer existing project dependencies and lockfiles. +- Pin versions instead of floating to latest when risk is high. +- Run package-manager audit checks after install when available. +- Avoid install-time scripts unless a dependency truly requires them. +- Do not add large dependency chains for decorative effects. +- Treat newly published, typosquatted, deprecated, or surprise-maintainer packages as suspicious. +- Prefer CSS/native APIs before adding a library for one small interaction. +- If a package ecosystem is under active incident response, wait or choose an existing/local stack. + +## Motion library fit + +- Static track: CSS transitions, native scroll-driven CSS, small vanilla JS. +- Vite + React: Motion/motion.dev for component/layout state, GSAP for timeline/pinned storytelling, CSS for simple feedback. +- Next: same as React, plus be careful with client/server boundaries. +- Astro: islands for isolated interactive parts; keep most content static. + +## Self-audit + +- Did the stack match the product surface, not the agent's habit? +- Did React buy real state/composition/animation value? +- Could static CSS/JS have done the same job with less risk? +- Are dependencies named, justified, and pinned/audited? +- Does the generated code still work if JavaScript loads slowly? diff --git a/plugins/f0d010c/stark/references/ux-patterns/README.md b/plugins/f0d010c/stark/references/ux-patterns/README.md new file mode 100644 index 000000000..6b4814ff9 --- /dev/null +++ b/plugins/f0d010c/stark/references/ux-patterns/README.md @@ -0,0 +1,15 @@ +# UX pattern briefs + +These are not generic templates. Use them as decision aids when a brief matches the context, user mode, risk, and frequency. + +Each brief should answer: + +- When this pattern applies +- When it is the wrong pattern +- What shipped products commonly do +- What failure it prevents +- What Stark should put in the UX decision brief + +Do not copy a referenced product screen. Extract the decision behind it, then adapt it to the user's product, platform, and constraints. + +When live references are available through tools such as Mobbin MCP or Figma, use them to enrich these briefs with current shipped examples. Treat those examples as evidence of real usage, not proof that the pattern always converts better. Use `../ui-patterns/reference-analysis.md` to extract structure instead of copying visuals. diff --git a/plugins/f0d010c/stark/references/ux-patterns/activation-onboarding.md b/plugins/f0d010c/stark/references/ux-patterns/activation-onboarding.md new file mode 100644 index 000000000..156e5b8d4 --- /dev/null +++ b/plugins/f0d010c/stark/references/ux-patterns/activation-onboarding.md @@ -0,0 +1,36 @@ +# Activation onboarding pattern + +Use when a user is new and must reach first value: setup flows, import flows, workspace creation, trial activation, first project creation, or profile/account setup. + +## Applies when + +- The user does not yet know whether the product is worth effort. +- The product needs setup before value appears. +- The flow has optional information that can be deferred. + +## Wrong when + +- The user is already expert and wants repeated speed. +- The product can show value immediately without setup. + +## Shipped-product signals to look for + +- First screen explains the concrete outcome, not the feature list. +- Required steps are visibly fewer than optional steps. +- Skip/resume exists for low-risk fields. +- Imported/demo/sample data can show value before full setup. +- Progress is meaningful, not decorative. +- Permissions are requested at the moment of need, with a concrete reason. +- Success state points to the next valuable action. + +## Failure prevented + +Long forms before value. Users drop when they pay setup cost before understanding the reward. + +## UX decision brief fields + +- Pattern: guided setup with skip/resume +- Primary action: reach first meaningful result +- Secondary actions: skip optional step, import data, use sample data, resume later +- Required states: no workspace, import running, import failed, permission denied, setup partial, first success +- Handoff constraints: do not force account/profile completion before value unless legally required diff --git a/plugins/f0d010c/stark/references/ux-patterns/ai-agent-run.md b/plugins/f0d010c/stark/references/ux-patterns/ai-agent-run.md new file mode 100644 index 000000000..bcc64c7ca --- /dev/null +++ b/plugins/f0d010c/stark/references/ux-patterns/ai-agent-run.md @@ -0,0 +1,35 @@ +# AI agent run pattern + +Use when the product asks an AI/tool/automation to do work that may take more than a few seconds: code agents, research agents, import jobs, render/export tasks, workflow automations, or background assistants. + +## Applies when + +- The user starts a task and must trust work happening out of sight. +- The result may include multiple artifacts, logs, changed files, or decisions. +- The user may need to stop, retry, resume, inspect, or correct the run. + +## Wrong when + +- The action completes instantly and has one obvious output. +- The system is only showing chat, with no external work or artifact state. + +## Shipped-product signals to look for + +- A plan preview before execution. +- A live progress surface with current step, elapsed time, and next likely step. +- Human-readable activity log, not raw implementation noise. +- Clear produced artifacts: files, links, screenshots, reports, diffs. +- Stop/cancel, retry failed step, resume from checkpoint. +- Final summary that separates completed work, skipped work, and user decisions needed. + +## Failure prevented + +Invisible work. Users lose trust when an agent says "working" without a plan, progress, or inspectable output. + +## UX decision brief fields + +- Pattern: plan preview + progress + artifacts + retry +- Primary action: start/approve run +- Secondary actions: stop, inspect log, retry step, open artifact +- Required states: queued, running, waiting for user, failed recoverably, failed terminally, complete +- Handoff constraints: progress must be visible without covering artifacts; final output must preserve traceability diff --git a/plugins/f0d010c/stark/references/ux-patterns/checkout-upgrade.md b/plugins/f0d010c/stark/references/ux-patterns/checkout-upgrade.md new file mode 100644 index 000000000..d29783d8c --- /dev/null +++ b/plugins/f0d010c/stark/references/ux-patterns/checkout-upgrade.md @@ -0,0 +1,36 @@ +# Checkout and upgrade pattern + +Use for checkout, subscription upgrade, paywall, pricing comparison, plan selection, add-ons, credits, usage limits, or trial conversion. + +## Applies when + +- The user is deciding whether to pay, upgrade, or commit. +- Trust, risk, price clarity, and reversibility matter. +- The user may compare options or worry about hidden terms. + +## Wrong when + +- The product is only browsing/catalog without commitment. +- The flow is an internal approval flow rather than a customer purchase. + +## Shipped-product signals to look for + +- Total cost and billing period are visible near the CTA. +- The CTA says what happens and, when useful, includes price. +- Plan comparison emphasizes differences that change the decision. +- Objection-handling copy is close to the moment of concern: cancellation, refunds, renewal, usage limits. +- No surprise fees late in the flow. +- Risk reversal appears as a product benefit, not legal footnote. +- Confirmation state repeats what was purchased and what happens next. + +## Failure prevented + +Trust collapse at commitment. Users back out when pricing, renewal, cancellation, or consequences feel hidden. + +## UX decision brief fields + +- Pattern: short form + transparent cost/risk + recovery +- Primary action: choose/confirm purchase or upgrade +- Secondary actions: compare plans, change quantity, apply code, cancel, contact sales +- Required states: loading price, invalid payment, failed payment, tax/shipping unavailable, success, refund/cancel path +- Handoff constraints: keep cost/terms near CTA; do not bury cancellation or renewal copy diff --git a/plugins/f0d010c/stark/references/ux-patterns/editor-canvas.md b/plugins/f0d010c/stark/references/ux-patterns/editor-canvas.md new file mode 100644 index 000000000..55c7aa16e --- /dev/null +++ b/plugins/f0d010c/stark/references/ux-patterns/editor-canvas.md @@ -0,0 +1,36 @@ +# Editor and canvas tool pattern + +Use for creative tools, document editors, image/video editors, builders, design surfaces, diagramming apps, IDE-like tools, and no-code builders. + +## Applies when + +- The user's main object is a canvas, document, timeline, board, or editable artifact. +- Users need direct manipulation, undo/redo, preview, and stable controls. +- Tool discovery matters, but the canvas must remain primary. + +## Wrong when + +- The main job is record triage, analytics, or checkout. +- The product is mostly static content or marketing. + +## Shipped-product signals to look for + +- Canvas is visually dominant and not trapped in decorative cards. +- Toolbars are stable, icon-led, and grouped by task. +- Selection state exposes contextual controls near the object or in a predictable inspector. +- Undo/redo is always available for destructive edits. +- Empty canvas suggests the first object/action. +- Autosave/saved state is visible but not noisy. +- Keyboard shortcuts exist for repeated expert actions. + +## Failure prevented + +Tool chrome overpowering creation. Editors fail when users fight panels instead of manipulating the artifact. + +## UX decision brief fields + +- Pattern: canvas + stable toolbar + inspector + undo/redo +- Primary action: create or edit the artifact +- Secondary actions: select, preview, undo, export, share, inspect properties +- Required states: blank canvas, selected object, unsaved/saving/saved, export running, edit conflict, permission blocked +- Handoff constraints: canvas must dominate; controls must not cause layout shift; destructive actions need undo diff --git a/plugins/f0d010c/stark/references/ux-patterns/operational-dashboard.md b/plugins/f0d010c/stark/references/ux-patterns/operational-dashboard.md new file mode 100644 index 000000000..748395c3b --- /dev/null +++ b/plugins/f0d010c/stark/references/ux-patterns/operational-dashboard.md @@ -0,0 +1,39 @@ +# Operational dashboard pattern + +Use for SaaS dashboards, admin panels, CRM views, support tools, analytics workspaces, moderation queues, inventory systems, and internal tools used repeatedly. + +## Applies when + +- Users return often and need speed more than delight. +- The product contains lists, filters, statuses, assignments, or alerts. +- Users compare, triage, bulk edit, or drill into records. + +## Wrong when + +- The screen is mainly a marketing hero or first-run onboarding. +- The product only has one or two simple actions and no repeated workflow. + +## Shipped-product signals to look for + +- A clear operational thesis: what is at risk, what queue is being worked, and what decision the operator should make next. +- Dense but readable tables or lists with persistent filters. +- Saved views for repeated jobs. +- Priority stack: what needs attention first. +- Master/detail or side panel to avoid losing list position. +- Bulk selection, batch actions, undo or confirmation for destructive actions. +- Inline status, ownership, timestamps, and audit trail. +- Empty state that teaches how data gets into the system. + +## Failure prevented + +Pretty-but-slow internal tools. Large cards, hidden filters, and decorative spacing make repeated work feel expensive. + +Generic dashboards are also a failure. If the screen could belong to any CRM, support desk, or admin panel after swapping the logo, the design has not understood the work. Use domain-specific signals, labels, states, and actions so the surface feels like a tool built for one job. + +## UX decision brief fields + +- Pattern: command surface + saved views, or master/detail + filters + bulk actions +- Primary action: the repeated task users do most +- Secondary actions: filter, save view, bulk action, drilldown, export +- Required states: empty, loading skeleton, partial data, permission blocked, stale data, bulk action in progress +- Handoff constraints: preserve scan speed; do not use landing-page spacing; keep table/list position stable; make the operational thesis visible in the first viewport diff --git a/plugins/f0d010c/stark/references/web-bans.md b/plugins/f0d010c/stark/references/web-bans.md new file mode 100644 index 000000000..98d48e1ab --- /dev/null +++ b/plugins/f0d010c/stark/references/web-bans.md @@ -0,0 +1,69 @@ +# Web — Anti-Slop Ban List (2026) + +Reject every item below by default. If the user explicitly requests one, push back once before complying. State why it's banned. + +## Color + +- `bg-gradient-to-r from-purple-500 to-pink-500` — the most-flagged AI tell. Adam Wathan apologized publicly. +- `from-indigo-500`, `bg-indigo-600`, "trust-blue" accents +- Slate-950 / zinc-950 backgrounds with no warmth/coolness bias (the "dark mode VS Code" look) +- Default shadcn theme untouched (the new Bootstrap) +- Pure `#000` backgrounds (use `oklch(0.18 0.02 280)` or warm-tinted near-black) +- Pure `#fff` backgrounds (use `#fafaf7` warm off-white) +- Confused dark mode: slate-950 + slate-300 text + one indigo accent + +## Typography + +- Inter (most common AI default) +- Space Grotesk (the second most common) +- Roboto, Arial, system-ui as primary face +- Identical font-weight throughout (use 400/500/600 sparingly, 700/800 for emphasis) +- Default Tailwind type scale untouched (the give-away) + +## Layout + +- Three feature cards in a row with Lucide icons + "Built for modern teams" copy +- Hero: H1 + sub + indigo primary button + ghost button (the universal SaaS skeleton) +- Hero + 3-column features + CTA strip + footer (the universal SaaS landing) +- Centered everything, no asymmetry +- Identical 80px section padding throughout — kills rhythm +- `rounded-2xl` everywhere uniformly +- Full-width sections with no overlap, no diagonal flow, no grid-breaking +- Bento grid that's static (every tile flat) — 2026 bento is interactive + +## Components + +- Glassmorphism cards over mesh gradient (without intent) +- Stock "AI sparkle" iconography +- Emoji bullets in feature lists +- Default shadcn `` with no reskin +- `border border-slate-200` everywhere with no variation +- Tabler / Heroicons as primary icon set with no curation + +## Motion + +- No motion at all (boring) OR scattered micro-interactions (noisy) +- Default Framer Motion `initial={{ opacity: 0 }} animate={{ opacity: 1 }}` (the universal AI motion) +- Linear / ease-in-out curves on UI (use spring physics or custom cubic-bezier) +- Hover states that just lift+shadow with no surprise + +## Stack tells + +- Tailwind v3 patterns when v4 is current (use `@theme` not `tailwind.config.js`) +- `bg-white` / `text-black` raw classes everywhere (use semantic tokens) +- `framer-motion` package (the package is now `motion` from motion.dev) +- Hardcoded responsive breakpoints when container queries fit +- `useState` for dark mode when `prefers-color-scheme` + `data-theme` works +- shadcn add-everything install — pick the components actually needed + +## Copy patterns + +- "Built for modern teams" +- "10x faster" +- "Reimagined" / "Redefining" / "The new way to" +- "Powered by AI" sparkle badge +- "Try free for 14 days" with no other CTA variation + +## What to do instead + +For every banned pattern, the alternative is in `references/awwwards-ceiling.md` and `references/web-fonts.md`. The default move is: pick a real aesthetic direction first, then let the direction dictate every choice. diff --git a/plugins/f0d010c/stark/references/web-copy-voice.md b/plugins/f0d010c/stark/references/web-copy-voice.md new file mode 100644 index 000000000..3f50d071d --- /dev/null +++ b/plugins/f0d010c/stark/references/web-copy-voice.md @@ -0,0 +1,122 @@ +# Web Copy Voice Guide + +Most AI-generated UI fails at copy as much as visuals. "Built for modern teams." "10x faster." "Reimagined." All AI-slop tells. + +## Sentence patterns by direction + +### Editorial Swiss +- Short declarative sentences +- Italic emphasis: "Most watches are made by *machines*. We are not most watches." +- Plain-spoken, slightly archaic +- Avoid: "we believe", "we craft", "passionate about" + +### Tactile brutalism +- Direct, blunt, declarative +- All caps acceptable +- Numbered: "01. We don't do briefings. 02. We don't do pitches." +- No softeners ("we believe", "perhaps") + +### Type-as-hero +- Single-word heroes ("INDEPENDENT", "FORM", "TIME") +- Manifestos in fragments +- Pull quotes treated as headlines +- Letterforms carry meaning, copy supports + +### Glow + grain +- Mood-driven, slightly mysterious +- Tech-poetic: "Made for the next decade" +- Avoid: "We're excited to announce" + +### Industrial monospace +- Technical, declarative +- Code-aware: `> 01 — initialize` +- Specs in `key=value` +- Avoid: emoji, conversational tone + +### Active bento +- Punchy tile titles ("Build faster") +- One-line tile subtitles +- Body content lives in detail view + +## Universal AI-slop ban list + +Reject these phrases by default: + +- "Built for modern teams" +- "Powered by AI" +- "Reimagined" / "Redefining" / "The new way to" +- "10x faster" / "10x productivity" +- "Try free for 14 days" (unless that's literally the product) +- "We're excited to announce" +- "Stop hating your [X]" +- "The [thing] that grows with you" +- "Thoughtfully designed for modern [audience]" +- "Crafted with care" +- "Beautiful, intuitive, fast" (always use these in marketing — banned) +- "Elevate your workflow" +- "Unlock your potential" +- "Seamlessly integrated" +- "Lorem ipsum" of any kind + +## Replacement patterns + +| Slop | Replacement | +|---|---| +| "Built for modern teams" | "Used by [actual customer types]" or skip entirely | +| "10x faster" | "[specific number] [specific metric]" | +| "Reimagined the [X]" | What you actually changed | +| "Thoughtfully designed" | Show the design, don't claim it | +| "Powered by AI" | Describe what it does | +| "Try free for 14 days" | "Free to start" or actual model | +| "Beautiful, intuitive" | Show, don't tell | + +## Editorial conventions + +- **Italic for emphasis** within headline, not bold +- **Em dash** for asides — like this — not parens +- **Numbers as numerals** in metadata (use `27 / 27`, not "twenty-seven") +- **Numbers as words** in body prose ("twenty-seven pieces a year, no more") +- **Single quotes** for "scare quotes", double for actual quotes +- **Hanging punctuation** — first character punctuation hangs into margin (`hanging-punctuation: first;`) +- **Mono caps for metadata** — dates, refs, status, version + +## Manifesto voice + +For brand/about/manifesto pages: + +- Open with a single sentence that's a position +- Follow with paragraph elaborating +- Use `§` numbering for sections +- Paragraphs 2-4 sentences max +- One memorable line per paragraph (the line you'd quote) +- Specifics > abstractions: "twenty-seven pieces a year" not "limited production" + +Example: +> § 01 — Manifesto +> +> Most watches are made by machines. We are not most watches. +> +> We don't out-source movement parts. We don't issue marketing campaigns. +> We don't release new collections every year. The watches we make +> spend years in development and weeks in finishing — and the people +> who own them tend to keep them for a lifetime. + +## Spec / metadata voice + +- `key — value` or `key: value` consistently +- All-caps mono for keys: `PRODUCTION`, `ATELIER`, `FOUNDED` +- Numbers always followed by unit: `27 pieces / yr`, `38 mm`, `60 h` +- Compact, never sentence + +## Self-audit + +Before shipping copy: + +1. Did I avoid every slop phrase above? +2. Are headlines under 8 words? +3. Are paragraphs under 4 sentences? +4. Did I use specifics, not abstractions? +5. Did I avoid em-dash overuse (>2 per paragraph)? +6. Italic / mono / weight used intentionally per direction? + +If "no" — rewrite that section, don't ship middle-mush copy. diff --git a/plugins/f0d010c/stark/references/web-direction-active-bento.md b/plugins/f0d010c/stark/references/web-direction-active-bento.md new file mode 100644 index 000000000..b96deb02a --- /dev/null +++ b/plugins/f0d010c/stark/references/web-direction-active-bento.md @@ -0,0 +1,114 @@ +# Direction — Active Bento + +Interactive bento tiles, expanding/morphing cards, autoplay video on hover, layered reveal. Not the static 2023 bento. Product-led, feature-driven. + +## Reference apps + +- linear.app/method — bento tiles that expand on hover +- vercel.com/templates — bento gallery +- arc.net — interactive feature tiles +- raycast.com (extensions section) — bento-style +- notion.com (features) — animated bento +- fly.io (architecture page) — technical bento +- replit.com (homepage) — feature tiles +- supabase.com (features grid) — animated bento + +## Typography + +| Slot | Face | Size scale | +|---|---|---| +| Display | Söhne / Inter Display / GT America | `clamp(40px, 6vw, 88px)` | +| Tile headline | Same, smaller | 24-32px | +| Body | Söhne / Inter Tight | 14-16px | +| Mono labels | Söhne Mono / JetBrains Mono | 11-12px | + +Restrained type — bento tiles ARE the visual content. + +## Palette + +- Per-tile distinct accents (each tile gets own color identity) +- Background: dark warm `#0A0907` or paper warm +- Tile borders: subtle (`border-white/[0.06]` on dark, `border-stone-200` on light) +- Strong accent per tile (extracted from content) + +## Layout grid + +- 12-col grid w/ irregular tile spans (tile A: 2x2, tile B: 1x2, tile C: 3x1, etc) +- Featured tile that's 2× others +- Magazine-asymmetric — not uniform 3-up +- `gap-4` to `gap-6` between tiles +- Tiles fill viewport on hover (View Transitions) + +## Motion language + +- **Layout animation** (Motion `layoutId`) — tile expands smoothly to detail view +- **Hover scale + lift** (`whileHover={{ y: -4, scale: 1.02 }}`) +- **Autoplay video on hover** — tile content morphs when interacted +- **Connected animation** — tile → detail page via shared `layoutId` +- **Scroll-snapping** — vertical bento sections snap-aligned +- **View Transitions** — bento → detail transition + +## Copy voice + +- Punchy tile titles ("Build faster", "Ship safer", "Scale wider") +- One-line subtitles per tile +- Body content lives in detail view, not tile +- Avoid: full paragraphs in tile (overflow kills hierarchy) + +## Sample structure + +``` +1. Nav (standard, wordmark + nav + CTA) +2. Hero (restrained — tile gallery is the star) +3. Bento grid (8-12 tiles, varying sizes, alternating accents) +4. Tile-detail expansions (layoutId connected) +5. Customer / press logos +6. Footer (compact) +``` + +## Direction-specific bans + +- Static identical 3-up grid (must vary) +- Same accent on every tile (per-tile distinct) +- Long body copy in tiles +- No interaction on tiles (bento must MOVE) +- Cards w/ generic shadow (use tonal elevation or border) + +## Sample tile + +```jsx + +
+
+ {label} +

{title}

+
+ +``` + +## Sample tokens + +```css +@theme { + --color-bg: #0A0907; + --color-bg-2: #14130F; + --color-fg: #F5F4EE; + --color-tile-1: #C53030; /* red */ + --color-tile-2: #7C3AED; /* purple */ + --color-tile-3: #0EA5E9; /* cyan */ + --color-tile-4: #10B981; /* green */ + --color-tile-5: #F59E0B; /* amber */ + --color-tile-6: #EC4899; /* pink */ + + --font-display: "Söhne", "Inter Display", system-ui, sans-serif; + --font-body: "Söhne", "Inter Tight", system-ui, sans-serif; + --font-mono: "Söhne Mono", "JetBrains Mono", monospace; +} +``` diff --git a/plugins/f0d010c/stark/references/web-direction-brutalist.md b/plugins/f0d010c/stark/references/web-direction-brutalist.md new file mode 100644 index 000000000..10574f931 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-direction-brutalist.md @@ -0,0 +1,101 @@ +# Direction — Tactile Brutalism + +Visible grids. Harsh type. Color clashes. Raw seams. Mono-driven. Anti-polish, intentional friction. "Human-made" reaction signal. + +## Reference apps + +- werkstatt.fyi — brutalist editorial +- fram.io — DIY/tape aesthetic +- off-brand.work — design studio brutalism +- dinamo.us — type foundry brutalist +- pentagram.com (selected projects) — restrained brutalism +- read.cv (early versions) — terminal-meets-resume +- ableton.com (loop sections) — Swiss brutalism + +## Typography + +| Slot | Face | Size scale | +|---|---|---| +| Display | Söhne Mono / Neue Haas Grotesk Mono / Authentic Sans | `clamp(40px, 7vw, 96px)` UPPERCASE | +| Headline | Neue Haas Grotesk Display / Authentic Sans | `clamp(28px, 4vw, 56px)` | +| Body | Neue Haas Grotesk Text / Söhne | 16px / 1.45 line-height | +| Mono | Söhne Mono / JetBrains Mono | 13px | + +Heavy weights (700-900). Tight tracking on display (`-0.04em`). All-caps acceptable. + +## Palette + +- Paper: `#F0F0EB` warm off-white OR pure `#000` (brutalist allows pure black) +- Ink: `#000` — pure black +- Accent 1 (hi-vis): `#FF3B00` orange OR `#FFE600` hi-vis yellow +- Accent 2 (clash): `#0066FF` industrial blue OR `#22FF00` digital green +- Mid: `#888` only + +Color clashes intentional. Pair `#FF3B00` w/ `#0066FF` for full brutalist signal. + +## Layout grid + +- Strict 8px grid, **visible** (background grid lines acceptable) +- Sharp corners (`border-radius: 0`) everywhere +- Thick borders (`2px-4px solid #000`) +- Block-level layout, no float / no flex magic +- Negative margins acceptable (overlap intentional) +- Skewed/rotated elements OK if grid still readable + +## Motion language + +- Snappy timing `cubic-bezier(0.85, 0, 0.15, 1)` 200ms — NO soft springs +- Mechanical, not organic +- Cursor-following SNAP to grid (not magnetic-soft) +- Scroll-snap sections +- `mix-blend-mode: difference` highlights +- No page-load curtain (instant render, raw start) + +Avoid: spring physics, slow easings, smooth scroll (Lenis), parallax (too soft). + +## Copy voice + +- Direct, blunt, declarative +- All-caps for headlines acceptable +- Numbered lists, log entries +- Short sentences. Period. +- Avoid: friendly tone, marketing softeners ("we believe", "we craft") + +## Sample structure + +``` +1. Raw nav (no border, no chrome — just text links + grid lines) +2. Hero (massive uppercase mono display + thick rule + log-style metadata) +3. Index / contents — list of sections with monospace dot leaders +4. Selected work (numbered, dense grid, no padding) +5. Process (numbered steps, mono, no animation) +6. Contact (block of text, no form polish) +7. Colophon (specs of the page itself — fonts, build, year) +``` + +## Direction-specific bans + +- Soft drop shadows (use thick borders) +- Rounded corners +- Spring/easeInOut motion +- Lenis smooth scroll (use raw native scroll) +- Glassmorphism / backdrop-filter +- Gradient backgrounds (solid color blocks only) +- Soft serif body text (mono / heavy grotesque only) +- Pastel palettes + +## Sample tokens + +```css +@theme { + --color-paper: #F0F0EB; + --color-ink: #000; + --color-rule: #000; + --color-accent: #FF3B00; + --color-accent-2: #FFE600; + + --font-display: "Söhne Mono", "Neue Haas Grotesk Mono", monospace; + --font-body: "Neue Haas Grotesk Text", "Söhne", system-ui, sans-serif; + --font-mono: "Söhne Mono", "JetBrains Mono", monospace; +} +``` diff --git a/plugins/f0d010c/stark/references/web-direction-editorial.md b/plugins/f0d010c/stark/references/web-direction-editorial.md new file mode 100644 index 000000000..869d30c9e --- /dev/null +++ b/plugins/f0d010c/stark/references/web-direction-editorial.md @@ -0,0 +1,106 @@ +# Direction — Editorial Swiss Revival + +Reading-room vibe. Considered restraint. Magazine spread digital. Generous whitespace. + +## Reference apps (study these) + +- rauchg.com — tech blog ceiling, restraint as the work +- are.na — editorial network, monospace metadata, generous whitespace +- robinrendle.com — letterforms, words.are.fluid +- Artifact Labs (`assets/screenshots/artifact-labs-site/`) — our sample +- the-pudding.cool — long-form editorial w/ data +- editorialnew.com (Pangram Pangram) — reference for the typeface itself +- shauninman.com — paragraph-driven blog +- maggieappleton.com — illustration + essay + +## Typography + +| Slot | Face | Size scale | +|---|---|---| +| Display | Newsreader / PP Editorial New / Tiempos Headline | `clamp(48px, 8.5vw, 144px)` | +| Headline | Newsreader / PP Editorial New | `clamp(36px, 6vw, 96px)` | +| Body | Inter Tight / Söhne / Tiempos Text | 17–18px / line-height 1.55 | +| Mono eyebrow | JetBrains Mono / Söhne Mono | 10px / `tracking-[0.32em] uppercase` | + +Italic emphasis within headline: `word`. + +## Palette + +- Paper: `#F1ECE2` warm off-white (never pure `#fff`) +- Paper-2 (sections): `#E7E1D4` +- Ink: `#1A1614` warm near-black (never pure `#000`) +- Ink-2 (secondary): `#4A4339` +- Ink-3 (tertiary): `#87796B` +- Rule (hairlines): `#C4BAA8` +- Single accent: oxblood `#6B1F1F` / coral `#C53030` / forest `#2D4A3F` + +One accent per project. Rule lines for separators, not borders. + +## Layout grid + +- 12-col, 8px gutter, asymmetric content +- Hero takes 7-8 cols, supporting meta in 2-3 col left rail +- `§ 01` `§ 02` numbering for sections, sticky in left rail +- Generous section padding (`py-32` to `py-44`) +- Body width: `max-w-[68ch]` for paragraph (60-70 char rule) +- Asymmetric featured grid alternates left/right + +## Motion language + +Pick 2-4 from these: +- Letter-stagger reveal on hero (spring physics, ~50ms stagger) +- `reveal-on-scroll` fade-up (CSS `animation-timeline: view()`) +- Variable-font weight hover on headlines +- Lenis smooth scroll (subtle, 1.2 duration) +- Sweeping highlight bar on scroll-progress through manifesto text + +Avoid: fast snappy timing (use `cubic-bezier(0.2, 0, 0, 1)` 600ms+). Editorial breathes. + +## Copy voice + +- Short editorial sentences. Plain-spoken. No marketing-speak. +- Manifesto: 2-3 line headline + 1-2 paragraph elaboration +- Italic for emphasis, not bold +- `§ 01 — Manifesto` section markers in mono caps +- Specs as definition lists (`
` / `
`) +- Avoid: "Built for modern teams", "10x faster", "Reimagined", "Powered by AI" + +## Sample structure + +``` +1. Nav (minimal — wordmark + 4 nav items + meta indicator) +2. Hero (large headline + italic emphasis + body paragraph + CTAs + interactive visual) +3. Manifesto (§ 01 — sticky left rail + headline + body + specs) +4. Marquee band (philosophical statements, italic display, slow scroll) +5. References / Featured (§ 02 — alternating asymmetric, watch / product per row) +6. Journal / Archive (§ 03 — dated entries, hover-weight title) +7. Footer (mega-wordmark closer + columns + colophon) +``` + +## Direction-specific bans + +- Bold sans-serif headlines (use serif display) +- Material elevation shadows (use rules + warm paper) +- Centered text columns (use asymmetric grid) +- Snappy motion (slow + spring) +- Pure white / pure black (warm tints) +- Decorative imagery for its own sake (let typography lead) +- "Hero + 3-cols-features + CTA + footer" SaaS skeleton + +## Sample tokens (DTCG-ish) + +```css +@theme { + --color-paper: #F1ECE2; + --color-paper-2:#E7E1D4; + --color-ink: #1A1614; + --color-ink-2: #4A4339; + --color-ink-3: #87796B; + --color-rule: #C4BAA8; + --color-accent: #6B1F1F; + + --font-display: "Newsreader", "Tiempos Headline", Georgia, serif; + --font-body: "Inter Tight", "Söhne", system-ui, sans-serif; + --font-mono: "JetBrains Mono", "Söhne Mono", ui-monospace, monospace; +} +``` diff --git a/plugins/f0d010c/stark/references/web-direction-glow-grain.md b/plugins/f0d010c/stark/references/web-direction-glow-grain.md new file mode 100644 index 000000000..6ff7c820e --- /dev/null +++ b/plugins/f0d010c/stark/references/web-direction-glow-grain.md @@ -0,0 +1,115 @@ +# Direction — Glow + Grain + +Multicolor glowing backdrops with tactile grain. Atmospheric mesh gradients. Dark-mode editorial. Atmosphere-driven, mood over message. + +## Reference apps + +- stripe.com / stripe.com/sessions — gradient mastery, layered atmospheres +- openai.com — restrained atmospheric dark +- vercel.com hero — animated gradient + grid +- liveblocks.io — Awwwards-tier glow motion +- runwayml.com — generative atmosphere +- midjourney.com (landing) — soft glow, dreamy +- linear.app — restrained glow + craft +- arc.net (browser.company) — color-glow brand + +## Typography + +| Slot | Face | Size scale | +|---|---|---| +| Display | Söhne / Inter Display / GT America | `clamp(48px, 8vw, 128px)` | +| Headline | Same | `clamp(32px, 5vw, 72px)` | +| Body | Söhne / Inter Tight | 16-17px / 1.55 line-height | +| Mono | JetBrains Mono / Söhne Mono | 11px / mono caps | + +Restrained sans-serif — atmosphere carries the mood, type stays clean. + +## Palette + +- Background: warm-tinted near-black `oklch(0.18 0.02 280)` or `#0A0908` +- Mid: stone-700 / stone-800 grays +- Glow stops: 3-4 colors mixed, each with low alpha + - Pink-purple `#A78BFA` / `#F472B6` + - Teal-blue `#22D3EE` / `#3B82F6` + - Orange-coral `#FB923C` / `#EC4899` +- Foreground text: paper white `#FAF8F3` (not pure white) +- One accent for CTAs + +## Layout grid + +- Standard 12-col asymmetric, content over atmosphere +- Hero is full-bleed atmospheric backdrop +- Sections layered with subtle gradient transitions +- Cards use `backdrop-filter: blur()` over glow background + +## Motion language + +- **Page-load curtain** — dark mask peels back, atmosphere reveals +- **Mesh gradient drift** — multi-stop radial gradients animate slowly (10-30s loops) +- **Scroll-driven glow shift** — atmosphere palette evolves down the page (different colors per section) +- **Magnetic CTAs** — atmospheric buttons with glow halo +- **Backdrop-filter scroll** — content blurs when scrolled past hero +- **Subtle particle / dust** — overlay texture for tactile grain + +Avoid: too many discrete motion moments, atmosphere should feel continuous. + +## Copy voice + +- Mood-driven, slightly mysterious or technical +- Fragment headlines acceptable ("Made for the next decade") +- Plain-spoken body, restrained marketing voice +- Avoid: "We're excited to announce", over-explaining + +## Sample structure + +``` +1. Atmospheric nav (transparent, blur-on-scroll) +2. Hero (mesh gradient backdrop + restrained type + single CTA) +3. Feature sections (each with own atmospheric tint shift) +4. Logo cloud / press (dimmed, atmosphere shows through) +5. Manifesto / vision (paragraph-driven, mood-led) +6. Footer (atmosphere fades, restrained type, contact) +``` + +## Direction-specific bans + +- Pure white background (atmosphere needs depth) +- Hard solid color blocks (let gradients flow) +- Too-bright colors (saturation kills atmosphere — use soft, mid-tone glows) +- Stark drop shadows (use halos / glows instead) +- Sharp clashes (this direction is moody, not aggressive) + +## Sample tokens + +```css +@theme { + --color-bg: oklch(0.18 0.02 280); + --color-bg-2: oklch(0.22 0.02 280); + --color-fg: #FAF8F3; + --color-fg-2: #B8B0A4; + --color-fg-3: #6E665C; + --color-accent: #FB923C; + + --glow-1: #A78BFA; /* purple */ + --glow-2: #22D3EE; /* teal */ + --glow-3: #FB923C; /* orange */ + + --font-display: "Söhne", "Inter Display", "GT America", system-ui, sans-serif; + --font-body: "Söhne", "Inter Tight", system-ui, sans-serif; + --font-mono: "Söhne Mono", "JetBrains Mono", monospace; +} +``` + +## Mesh gradient scaffold + +```jsx +
+
+
+
+
{/* svg grain at 4% opacity */} +
+``` diff --git a/plugins/f0d010c/stark/references/web-direction-industrial-mono.md b/plugins/f0d010c/stark/references/web-direction-industrial-mono.md new file mode 100644 index 000000000..c6de9071b --- /dev/null +++ b/plugins/f0d010c/stark/references/web-direction-industrial-mono.md @@ -0,0 +1,121 @@ +# Direction — Industrial Monospace + +Söhne Mono / JetBrains Mono everywhere. Terminal references. Log-driven hero. Technical aesthetic, no decoration. Dev-tool benchmark. + +## Reference apps + +- railway.com — serious editorial polish on technical content +- fly.io — terminal-driven brand +- raycast.com — dark craft, micro-interactions +- resend.com — type-driven dev tool benchmark, mostly mono +- supabase.com (older versions) +- modal.com — clean technical +- vercel.com /docs — restrained tech +- temporal.io — technical content, mono accents +- ngrok.com — terminal-meets-marketing + +## Typography + +| Slot | Face | Size scale | +|---|---|---| +| Display | Söhne Mono / JetBrains Mono — yes mono for display | `clamp(40px, 6.5vw, 96px)` | +| Headline | Same | `clamp(28px, 4.5vw, 64px)` | +| Body | Söhne / Inter Tight (small mono accents) | 15-16px / 1.5 | +| Mono | Söhne Mono / JetBrains Mono / IBM Plex Mono | 13px | +| Code | Same mono | 13-14px in code blocks | + +Mono everywhere, body grotesque for readability. + +## Palette + +- Background: dark warm `#0A0907` or paper `#F5F3EE` (industrial allows both) +- Foreground: stone-100 `#F5F4EE` or ink `#0A0908` +- Accent: green terminal `#00FF66` / `#10B981` or amber `#F59E0B` (terminal-vintage) +- Rule lines: thin, monospaced character widths +- No gradients (industrial = solid) + +## Layout grid + +- Code-block-driven sections +- Numbered like log entries (`> 01 — initialize`) +- Box-shadow-as-line for boundary (`1px solid currentColor`) +- Terminal-style header / footer with timestamp + status +- Inline code embedded in body + +## Motion language + +- Typewriter intro (letter-by-letter on hero — dev-tool signature) +- Cursor blink at end of typed text +- Number tickers (port count, latency, version increment) +- Log-stream marquee (lines scroll up like console) +- Terminal-style page transitions (clear-screen + retype) +- Micro: hover-flip glyph (e.g. `→` becomes `↗`) + +Avoid: spring physics (mechanical only), smooth-scroll Lenis (raw native), glow effects (industrial is dry). + +## Copy voice + +- Technical, declarative +- Code-aware: shell prompts (`$`, `>`, `~`) +- Numbered list of features as `01 02 03` mono +- Specs in `key=value` syntax +- No marketing softeners +- Avoid: emoji, conversational tone + +## Sample structure + +``` +1. Terminal-style nav (wordmark in mono + numbered nav items) +2. Hero (typewriter headline + terminal cursor + spec block beneath) +3. Why section (numbered 01 02 03, mono) +4. Features as code blocks (shell snippets, output examples) +5. Pricing as table (mono, ASCII art borders OK) +6. Docs preview (live code editor) +7. Footer (timestamp + version + minimal links) +``` + +## Direction-specific bans + +- Serif body text (mono and grotesque only) +- Soft drop shadows +- Glow effects +- Spring physics on motion +- Decorative imagery (terminal aesthetic — no flourishes) +- Pastel colors +- Centered hero block (left-align like a code block) + +## Sample tokens + +```css +@theme { + --color-bg: #0A0907; + --color-bg-2: #14130F; + --color-fg: #F5F4EE; + --color-fg-2: #A8A39A; + --color-fg-3: #6E665C; + --color-accent: #10B981; /* terminal green */ + + --font-display: "Söhne Mono", "JetBrains Mono", "IBM Plex Mono", monospace; + --font-body: "Söhne", "Inter Tight", system-ui, sans-serif; + --font-mono: "Söhne Mono", "JetBrains Mono", monospace; +} +``` + +## Typewriter intro + +```jsx +import { useEffect, useState } from "react"; + +function Typewriter({ text, speed = 35 }: { text: string; speed?: number }) { + const [out, setOut] = useState(""); + useEffect(() => { + let i = 0; + const t = setInterval(() => { + setOut(text.slice(0, i++)); + if (i > text.length) clearInterval(t); + }, speed); + return () => clearInterval(t); + }, [text, speed]); + return {out}▋; +} +``` diff --git a/plugins/f0d010c/stark/references/web-direction-type-as-hero.md b/plugins/f0d010c/stark/references/web-direction-type-as-hero.md new file mode 100644 index 000000000..8cfa35fed --- /dev/null +++ b/plugins/f0d010c/stark/references/web-direction-type-as-hero.md @@ -0,0 +1,103 @@ +# Direction — Type-as-Hero + +Oversized variable display fonts. Scroll-morphing letterforms. No decorative imagery. Type IS the design. Maximalist typography flex. + +## Reference apps + +- igloo.inc — Awwwards SOTY 2025 (3D + massive type) +- lehman.berlin — restraint + signature display +- Lando Norris official site (off-brand) — Awwwards SOTY-tier oversized type +- pangrampangram.com — type foundry, type IS the product +- ohnotype.co — display type w/ specimen heroes +- newedge.studio — display-driven brand +- monumentvalleygame.com — game site, type flex +- type.today — type foundry, type-led + +## Typography + +| Slot | Face | Size scale | +|---|---|---| +| Mega-display | Variable serif (PP Editorial New, GT Sectra, Reckless Neue) OR variable grotesque (Söhne Variable, Bricolage Grotesque) | `clamp(120px, 22vw, 320px)` | +| Headline | Same family, smaller weight | `clamp(48px, 8vw, 128px)` | +| Body | Restrained grotesque (Söhne, Inter Tight) | 14-16px / 1.4 line-height | +| Metadata | Mono | 10-11px / `tracking-[0.32em] uppercase` | + +Use variable axes aggressively — `wght`, `opsz`, `wdth`, `grade`, `slnt`. + +## Palette + +- Two-tone is standard — paper + ink only, type carries everything +- Optional: ONE accent for hover states +- Background gradients OK as atmospheric scaffold (not decoration) + +## Layout grid + +- Type fills viewport — letterforms become composition +- Mega-letters that crop intentionally at edges +- Asymmetric, type-led layout — body content fits where type allows +- Single hero word can fill entire viewport +- Specimen-style: letter A, letter B, letter C as anchors +- Vertical type acceptable + +## Motion language + +Heavy hitters in this direction: +- **Page-load curtain reveal** — letterforms emerge from masked layer +- **Scroll-pinned headline morph** — type scales / unscales / rotates as scroll progresses (via GSAP ScrollTrigger or Motion `useTransform`) +- **Variable-axis cursor-Y hover** — headline weight responds to mouse Y position +- **Letter-by-letter stagger** — slow, considered, dramatic +- **3D type extrusion** — perspective depth on letterforms +- **GSAP SplitText** — letter-by-letter or line-by-line entrance +- **Mesh gradient atmospheres** behind type — color picks up through letterforms via `mix-blend-mode: difference` or `screen` + +## Copy voice + +- Single-word heroes ("RESONANCE", "INDEPENDENT", "FORM") +- Manifestos in fragments +- Pull quotes treated as headlines +- Avoid: descriptive paragraphs (let type carry meaning) + +## Sample structure + +``` +1. Nav (minimal — wordmark + 1-2 links, almost invisible) +2. Hero (mega-type filling viewport, single word OR short phrase) +3. Sub-hero (smaller type explaining, body width tight) +4. Specimen sections — character A, B, C with descriptions +5. Body content (small, restrained, lets specimen breathe) +6. Footer (mega-wordmark closer — full-viewport) +``` + +## Direction-specific bans + +- Decorative imagery (illustrations, photos, icons distracting from type) +- Body text larger than 18px (type IS hero, body is supporting) +- Multiple accents (type carries; color is one tool) +- Heavy decoration (rules, gradients, etc) — type alone +- Centered everything — type-as-hero asymmetric + +## Sample tokens + +```css +@theme { + --color-paper: #F1ECE2; + --color-ink: #0A0908; + + --font-display: "PP Editorial New", "GT Sectra", "Reckless Neue", serif; + --font-body: "Söhne", "Inter Tight", system-ui, sans-serif; + --font-mono: "Söhne Mono", "JetBrains Mono", monospace; +} +``` + +## Variable-axis trick + +```css +.headline { + font-family: var(--font-display); + font-variation-settings: "wght" 400, "opsz" 72; + transition: font-variation-settings 600ms cubic-bezier(0.2, 0, 0, 1); +} +.headline:hover { + font-variation-settings: "wght" 800, "opsz" 144; +} +``` diff --git a/plugins/f0d010c/stark/references/web-fonts.md b/plugins/f0d010c/stark/references/web-fonts.md new file mode 100644 index 000000000..ec096762e --- /dev/null +++ b/plugins/f0d010c/stark/references/web-fonts.md @@ -0,0 +1,79 @@ +# Web Typography — Curated Pairs (2026) + +Use one of these pairs unless the brief demands otherwise. All are battle-tested on 2025–2026 award sites. + +## Tier 1: distinctive defaults + +| Display | Body | Mono | Vibe | Source | +|---|---|---|---|---| +| PP Editorial New | PP Neue Montreal | PP Neue Montreal Mono | Magazine + grotesque | Pangram Pangram | +| PP Editorial Old | PP Formula | PP Formula Mono | '70s serif + geometric | Pangram Pangram | +| Söhne | Tiempos Text | Söhne Mono | Klim workhorse | Klim Type Foundry | +| Newsreader | JetBrains Mono | JetBrains Mono | Neo-serif + dev mono | Google Fonts + JetBrains | +| GT Sectra | GT America | GT America Mono | Grilli Type | Grilli Type | +| Söhne Mono | Söhne | Söhne Mono | Tech-brand mono-driven | Klim | +| ABC Diatype | ABC Diatype Mono | ABC Diatype Mono | Dinamo, design-tool aesthetic | Dinamo | +| Cabinet Grotesk | Satoshi | JetBrains Mono | Indie Pangram alt | Indie/Fontshare | + +## Tier 2: when something specific is needed + +| Use case | Font | Why | +|---|---|---| +| Editorial / luxury | New Edge 666, Saol, Apoc Revelations | Strong contrast serif faces | +| Brutalist / utilitarian | Authentic Sans, Neue Haas Grotesk Mono | Raw character | +| Playful / consumer | Migra, Reckless, Paradigm | Bouncy, opinionated | +| Cyber / industrial | NB Akademie, Nuze, FK Grotesk | Sharp angles | +| Editorial / type-as-hero | Migra, Reckless Neue, NaN Holo | Big-set characterful display | +| Variable axis play | Roboto Flex, Inter (axis-flex variant), Satoshi Variable | Allow `font-variation-settings` hover micro-interactions | + +## Tier 3: free / Google Fonts only + +If the project must use only Google Fonts (no licensed faces): + +| Display | Body | Mono | +|---|---|---| +| Bricolage Grotesque | Inter Tight | JetBrains Mono | +| Fraunces (variable) | Inter Tight | JetBrains Mono | +| Instrument Serif | Geist | Geist Mono | +| Newsreader | Geist | Geist Mono | +| Boldonse | Manrope | Geist Mono | + +`Geist` (from Vercel) is acceptable; it's not Inter and not Space Grotesk. Use it as a body face, not a display. + +## Banned outright + +- **Inter** — the most common AI default +- **Space Grotesk** — the second most common +- **Roboto, Arial, system-ui as primary face** +- **Poppins** — overused 2018-2022 default +- Default Tailwind type scale untouched (50/60/72 — pick something else) + +## Variable axis tricks + +Pair a variable display face with body for hover micro-interactions: + +```css +.headline { + font-family: 'Söhne Variable', sans-serif; + font-variation-settings: "wght" 400, "opsz" 96; + transition: font-variation-settings 400ms cubic-bezier(0.2, 0, 0, 1); +} +.headline:hover { + font-variation-settings: "wght" 700, "opsz" 144; +} +``` + +This is the kind of detail that distinguishes designed-by-a-person output from generated output. Use it sparingly. + +## Self-host in 2026 + +Use [Fontsource](https://fontsource.org) for Google Fonts and Pangram Pangram licenses for paid faces. Self-hosting is faster than Google Fonts CDN and gives full control over font-display and unicode-range subsetting. + +```css +@font-face { + font-family: 'PP Editorial New'; + src: url('/fonts/PPEditorialNew-Regular.woff2') format('woff2-variations'); + font-weight: 100 900; + font-display: swap; +} +``` diff --git a/plugins/f0d010c/stark/references/web-layouts.md b/plugins/f0d010c/stark/references/web-layouts.md new file mode 100644 index 000000000..222a18b01 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-layouts.md @@ -0,0 +1,157 @@ +# Web Layout Pattern Catalog + +When to use which layout. Pair with direction picked. + +## 1. Hero + Rail (editorial standard) + +``` +┌─────────────────────────────────────────────┐ +│ NAV │ +├──────┬──────────────────────────────────────┤ +│ │ │ +│ § 01 │ Hero text (8 cols) │ +│ Meta │ Subtitle │ +│ rail │ CTAs │ +│ (2) │ │ +│ │ │ +└──────┴──────────────────────────────────────┘ +``` + +Sticky `§ 01` rail on left. Content takes 8-10 cols. Best for editorial, manifesto pages. + +## 2. Manifesto + Specs + +Two-column body. Long-form text on left (7 cols), spec list on right (5 cols). + +``` +┌──────────────────────────┬──────────────────┐ +│ Long-form prose │ Production: 27/yr│ +│ paragraph paragraph │ Atelier: CH │ +│ paragraph paragraph │ Founded: 2019 │ +│ paragraph │ Calibers: HC.7… │ +└──────────────────────────┴──────────────────┘ +``` + +## 3. Featured asymmetric (alternating sides) + +``` +┌─────────┬───────────────────────────────────┐ +│ Image 1 │ Title 1, copy, specs │ +└─────────┴───────────────────────────────────┘ +┌───────────────────────────────────┬─────────┐ +│ Title 2, copy, specs │ Image 2 │ +└───────────────────────────────────┴─────────┘ +┌─────────┬───────────────────────────────────┐ +│ Image 3 │ Title 3, copy, specs │ +└─────────┴───────────────────────────────────┘ +``` + +Alternating L/R sides break the SaaS template. 5/7 col split. + +## 4. Bento gallery (active) + +``` +┌──────────────┬────────┬────────┐ +│ │ Tile │ Tile │ +│ Big tile ├────────┴────────┤ +│ (2x2) │ Tile (2x1) │ +├────────┬─────┴────────────────┤ +│ Tile │ Tile (3x1) │ +└────────┴────────────────────────┘ +``` + +Irregular tile spans. Featured tile 2× others. + +## 5. Magazine spread + +Multi-column body w/ large display headline at top. Drop caps. Hanging punctuation. + +## 6. Type-as-Hero (single mega-word) + +``` +┌─────────────────────────────────────────────┐ +│ │ +│ │ +│ RESONANCE │ +│ │ +│ │ +│ Small body text below │ +└─────────────────────────────────────────────┘ +``` + +Single word fills viewport. All other content scaled smaller. + +## 7. Marquee divider + +Full-width text band between sections. Slow horizontal scroll. Editorial transition. + +## 8. Index / Archive list + +``` +───────────────────────────────────────────── +Mar 14 2026 | Title of entry | Read → +───────────────────────────────────────────── +Feb 02 2026 | Title of entry | Read → +───────────────────────────────────────────── +``` + +Date | Title | Action. Hover-weight title transition. + +## 9. Footer mega-wordmark + +``` +───────────────────────────────────────────── + + HAYES & Co. + + Independent watchmaker. + +───────────────────────────────────────────── +© 2026 · Made to outlast us · All rights reserved +``` + +Mega wordmark fills viewport width. Lusion / Studio Freight signature closer. + +## 10. Pinned scroll-tied section + +Pin viewport, content advances frame-by-frame as scroll progresses. See `web-patterns/scroll-pinned-section.md`. + +## 11. Product proof workbench + +Hero or first app section centered on a believable product surface: annotated UI preview, command palette, timeline replay, inspector pane, or trust matrix. Use for developer tools, AI products, security products, and workflow automation. + +Keep the product proof inspectable: real labels, stateful rows, visible errors, permissions, or run steps. Avoid dark blurred screenshots and generic dashboards. + +## 12. Docs + console split + +Docs or API reference layout with a stable left nav, readable content column, sticky right rail, and an optional live console/code sample pane. Use for SDKs, CLIs, plugin docs, and platform products. + +On mobile, collapse nav to a sheet and keep code samples copyable without horizontal layout breakage. + +## 13. Trust and permissions surface + +Matrix, comparison, or settings layout that makes risk legible: actor, scope, action, approval state, audit trail, and recovery path. Use for auth, admin, enterprise, marketplace, and plugin-install flows. + +Prefer dense but calm tables over decorative cards. Show empty, warning, denied, inherited, and pending states. + +## 14. Interactive comparison + +Before/after slider, pricing comparison table, or state gallery that helps users compare tradeoffs directly. Use when the decision is not obvious from prose alone. + +Keep comparison axes stable. Do not move labels, totals, or primary actions between states. + +## Avoid these layouts + +- Hero + 3-column features + CTA + footer (universal SaaS) +- Centered-everything (max-w-3xl mx-auto) +- Equal-span uniform grids +- Sidebar nav on marketing site (use top nav unless app) +- Sticky table-of-contents (unless docs) +- Marketing pages pretending to be apps without product proof + +## Composition rules + +- Vary section padding intentionally — `py-32`, `py-44`, `py-56` mix +- Break out of constraint mid-page (one section full-bleed, others contained) +- Mix wide and narrow content (one section `max-w-prose`, next `max-w-7xl`) +- Asymmetric wins over symmetric — center is the AI-slop default diff --git a/plugins/f0d010c/stark/references/web-motion.md b/plugins/f0d010c/stark/references/web-motion.md new file mode 100644 index 000000000..c1db1aedc --- /dev/null +++ b/plugins/f0d010c/stark/references/web-motion.md @@ -0,0 +1,127 @@ +# Web Motion — Library + Technique Inventory (2026) + +The model has wide motion vocabulary. Pick 2-4 signature moments per project, not all at once. + +## Library landscape + +| Library | Use for | Notes | +|---|---|---| +| **motion** (motion.dev) | React component motion, springs, layout animation, `useScroll`, `useTransform` | Successor to Framer Motion. ~30M monthly npm. 2.5-6× faster than GSAP on key paths. MIT. **Default for React.** | +| **GSAP** | Timelines, complex sequencing, SVG morphing, ScrollTrigger, SplitText | Now 100% free including SplitText / MorphSVG / DrawSVG (Webflow acquisition). Best for scroll-tied complex sequences. | +| **Theatre.js** | Cinematic 3D / R3F sequences with visual editor | Pair with single rAF loop. Niche, when needed. | +| **Lenis** | Smooth scroll | De facto on award sites. Use sparingly — native scroll fine for most. | +| **View Transitions API** | Native route transitions, shared element | Chrome/Edge/Safari 18.2+/Firefox 142+. Replaces FLIP for most cases. **Use for SPA navigation.** | +| **Native CSS scroll-driven** | `animation-timeline: view()` / `scroll()` | Chrome 115+ / Safari 26+ / Firefox 142+. Zero-JS reveals + progress bars. | + +## Technique inventory (bookmark per pattern) + +Each has dedicated reference at `web-patterns/.md`. Don't deploy all on one project. + +| Technique | Direction fit | Reference | +|---|---|---| +| Page-load curtain reveal | editorial, type-as-hero, glow-grain | `web-patterns/page-load-curtain.md` | +| Custom cursor | editorial, type-as-hero, glow-grain, active-bento | `web-patterns/custom-cursor.md` | +| Magnetic CTA | editorial, glow-grain, type-as-hero | `web-patterns/magnetic-button.md` | +| Scroll-pinned section | all (1 per page max) | `web-patterns/scroll-pinned-section.md` | +| View Transitions (route) | all w/ multi-page | `web-patterns/view-transitions.md` | +| Letter / word stagger | editorial, type-as-hero, glow-grain | `web-patterns/letter-stagger.md` | +| Variable-font hover | editorial (subtle), type-as-hero (signature) | `web-patterns/variable-font-hover.md` | +| Marquee band | editorial, brutalist, type-as-hero, industrial-mono | `web-patterns/marquee.md` | +| Layered parallax | editorial, type-as-hero, glow-grain | `web-patterns/parallax-layers.md` | +| 3D tilt card | editorial (interactive), active-bento, glow-grain | `web-patterns/3d-tilt-card.md` | +| Sticky § markers | editorial, type-as-hero, industrial-mono | `web-patterns/sticky-section-markers.md` | +| Native scroll-driven CSS | editorial, all | `web-patterns/scroll-driven-css.md` | +| Lenis smooth scroll | editorial, type-as-hero, glow-grain | `web-patterns/lenis-smooth-scroll.md` | +| Asymmetric grid | editorial, type-as-hero, glow-grain | `web-patterns/asymmetric-grid.md` | +| Symbol / glyph cycling | editorial, industrial-mono | `web-patterns/symbol-cycling-hover.md` | +| Connected animation (`layoutId`) | active-bento, editorial gallery→detail | `web-patterns/connected-animation.md` | +| Mesh gradient atmosphere | glow-grain (signature), type-as-hero, active-bento | `web-patterns/mesh-gradient.md` | +| Command palette | app shells, docs, devtools | `web-patterns/command-palette.md` | +| Inspector split pane | devtools, editors, audit tools | `web-patterns/inspector-split-pane.md` | +| Annotated product proof | SaaS, AI tools, security products | `web-patterns/annotated-product-proof.md` | +| Before/after slider | migrations, optimization, design systems | `web-patterns/before-after-slider.md` | +| Timeline / run replay | agents, CI, deploys, automations | `web-patterns/timeline-run-replay.md` | +| Permission / trust matrix | security, admin, enterprise settings | `web-patterns/permission-trust-matrix.md` | +| Empty state gallery | dashboards, onboarding, data apps | `web-patterns/empty-state-gallery.md` | +| Pricing comparison table | SaaS, developer tools, marketplaces | `web-patterns/pricing-comparison-table.md` | +| Docs / API reference layout | SDKs, CLIs, platform products | `web-patterns/docs-api-reference-layout.md` | +| Keyboard shortcut overlay | editors, command surfaces, power tools | `web-patterns/keyboard-shortcut-overlay.md` | + +## When to deploy how many + +- **1-2 motion moments** — minimum. Anything less = boring. +- **2-4 motion moments** — sweet spot for awwwards-tier. Each reinforces direction. +- **5+ motion moments** — usually over-motion. Becomes its own AI-tell. + +## Signature moments per direction + +- **Editorial**: letter stagger + reveal-on-scroll + var-font hover + Lenis +- **Brutalist**: instant render + cursor snap + marquee + mix-blend-difference +- **Type-as-hero**: page-load curtain + scroll-pinned headline morph + var-axis cursor-Y + mesh atmosphere +- **Glow + grain**: page-load curtain + mesh drift + scroll-driven glow shift + magnetic CTAs +- **Industrial mono**: typewriter intro + log marquee + monospace tickers + glyph cycle hover +- **Active bento**: layoutId connected + tile-expand hover + scroll-snap + custom cursor "VIEW" +- **Product proof**: annotated product preview + command palette + timeline/run replay + trust matrix + +## Default page-load reveal sequence (editorial) + +1. Initial mask/curtain animates off (200-400ms) +2. Background grain/glow fades in (300ms, eased) +3. Hero type reveals via stagger — line-by-line (50ms stagger between lines, spring physics) +4. Above-fold visual elements settle on spring (400-600ms) + +Total: under 1.2s. Longer = over-animated. + +## Spring physics defaults + +```ts +// Restrained editorial +{ type: "spring", stiffness: 130, damping: 20 } + +// Snappy active-bento +{ type: "spring", stiffness: 300, damping: 25 } + +// Slow cinematic +{ type: "spring", stiffness: 80, damping: 22 } + +// Bouncy fun +{ type: "spring", stiffness: 200, damping: 12 } +``` + +## Easing defaults (when not spring) + +- Snappy mechanical: `cubic-bezier(0.85, 0, 0.15, 1)` — brutalist, industrial +- Soft considered: `cubic-bezier(0.2, 0, 0, 1)` — editorial, glow +- Custom flourish: `cubic-bezier(0.65, 0.05, 0.36, 1)` — type-as-hero + +## prefers-reduced-motion (always honor) + +```css +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; + transition-duration: 0.01ms !important; + } +} +``` + +In Motion: +```tsx +import { useReducedMotion } from "motion/react"; +const reduce = useReducedMotion(); + +``` + +Failing this is an accessibility violation, not a stylistic choice. + +## Sources + +- motion docs: https://motion.dev/docs +- GSAP docs: https://gsap.com/docs +- View Transitions: https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API +- Native scroll-driven: https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline +- Lenis: https://lenis.darkroom.engineering diff --git a/plugins/f0d010c/stark/references/web-patterns/3d-tilt-card.md b/plugins/f0d010c/stark/references/web-patterns/3d-tilt-card.md new file mode 100644 index 000000000..7447f1fae --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/3d-tilt-card.md @@ -0,0 +1,62 @@ +# Pattern — 3D tilt card + +Perspective + rotateX/Y tracks cursor position. Adds depth to hero element / featured card. + +**When to deploy**: editorial (interactive product), active-bento (tile interaction), glow+grain (atmospheric depth). + +```tsx +import { motion, useMotionValue, useSpring } from "motion/react"; +import { useRef } from "react"; + +export function TiltCard({ children, max = 8 }: { children: React.ReactNode; max?: number }) { + const ref = useRef(null); + const rx = useMotionValue(0); + const ry = useMotionValue(0); + const sx = useSpring(rx, { stiffness: 150, damping: 18 }); + const sy = useSpring(ry, { stiffness: 150, damping: 18 }); + + return ( + { + const r = ref.current!.getBoundingClientRect(); + const x = (e.clientX - r.left) / r.width - 0.5; + const y = (e.clientY - r.top) / r.height - 0.5; + rx.set(-y * max); + ry.set(x * max); + }} + onPointerLeave={() => { rx.set(0); ry.set(0); }} + style={{ + rotateX: sx, + rotateY: sy, + transformStyle: "preserve-3d", + perspective: "1200px", + }} + > + {children} + + ); +} +``` + +## Inner depth + +Children with `transform: translateZ(60px)` float above card surface — adds dramatic 3D feel. + +```tsx + +
+
+
+

Floats above

+
+
+ +``` + +## Tradeoffs + +- Tilt strength `max` — 4-8 for subtle, 8-15 for dramatic +- Spring stiffness 150-300, damping 18-25 (more damping = settles faster) +- Disable on touch devices (`@media (hover: none) { ... }`) +- Avoid on type-heavy cards (rotation hurts readability) diff --git a/plugins/f0d010c/stark/references/web-patterns/README.md b/plugins/f0d010c/stark/references/web-patterns/README.md new file mode 100644 index 000000000..72fbe5b7d --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/README.md @@ -0,0 +1,61 @@ +# Web pattern index + +Use this folder as a pattern palette, not a checklist. Pick two to four patterns that serve the surface type and product job. + +## Marketing and brand pages + +Use when the goal is memory, trust, and conversion. + +- `annotated-product-proof.md` - strongest default for serious tools; shows the product instead of only claiming value. +- `before-after-slider.md` - useful when transformation is the value. +- `asymmetric-grid.md` - gives editorial rhythm without relying on decoration. +- `scroll-pinned-section.md` - good for step-by-step narratives, but keep it short. +- `letter-stagger.md` or `variable-font-hover.md` - one typographic signature move. +- `page-load-curtain.md` - only when the site has a deliberate editorial or launch feel. + +Avoid using all motion patterns at once. A page with too many tricks feels less premium. + +## SaaS dashboards and operational tools + +Use when the product is used repeatedly. + +- `inspector-split-pane.md` - best for list/detail workflows, alerts, tickets, runs, CRM records, and audits. +- `command-palette.md` - best for expert shortcuts without hiding mouse paths. +- `keyboard-shortcut-overlay.md` - useful once a tool has repeat workflows. +- `timeline-run-replay.md` - best for deploys, AI agent runs, background jobs, audits, and incident workflows. +- `permission-trust-matrix.md` - best for admin, team, billing, and security surfaces. +- `empty-state-gallery.md` - best for defining first-run and no-data states. + +Prefer stable layout, visible filters, saved views, and clear state over spectacle. + +## Docs, API, and developer tools + +Use when comprehension speed matters. + +- `docs-api-reference-layout.md` - docs with nav, content, code, and copyable examples. +- `command-palette.md` - quick navigation and actions. +- `annotated-product-proof.md` - show the API/workflow in context. +- `timeline-run-replay.md` - explain build, deploy, test, or agent execution. + +## Pricing, checkout, and trust + +Use when the user is making a cost or risk decision. + +- `pricing-comparison-table.md` - plan clarity. +- `permission-trust-matrix.md` - access, data, compliance, and admin confidence. +- `before-after-slider.md` - value delta when upgrading. +- `empty-state-gallery.md` - explain what happens before data or access exists. + +## Pattern choice rule + +Choose patterns by failure mode: + +| Failure risk | Prefer | +|---|---| +| User does not understand value | annotated product proof | +| User cannot compare options | pricing comparison table / before-after slider | +| User loses place in dense work | inspector split pane | +| User cannot trust action safety | permission/trust matrix | +| User cannot track background work | timeline/run replay | +| Power users are slowed down | command palette / shortcut overlay | +| First-run feels blank | empty-state gallery | diff --git a/plugins/f0d010c/stark/references/web-patterns/annotated-product-proof.md b/plugins/f0d010c/stark/references/web-patterns/annotated-product-proof.md new file mode 100644 index 000000000..ef40eaef1 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/annotated-product-proof.md @@ -0,0 +1,29 @@ +# Pattern - Annotated product proof + +Use on marketing pages for technical products where the first viewport must prove the product is real: devtools, dashboards, local agents, security tools, analytics, AI tools, and workflow software. + +## Structure + +- One believable product screenshot or code-rendered UI preview. +- 2-5 annotations tied to actual user value. +- Labels point to concrete states: failed check, masked secret, stale deploy, permission request, retry queue, selected artifact. +- Annotation copy explains why the detail matters. +- Keep the product UI readable enough that users can inspect it. + +## Asset choices + +- Prefer real product screenshots with permission or generated/code-rendered product mocks for fictional products. +- Use generated bitmap imagery only when it adds context that the UI itself cannot show. +- Store attribution for external screenshots. + +## Responsive + +- Desktop: callouts can sit outside the screenshot with connector lines. +- Mobile: stack callouts below the cropped proof or use numbered markers. + +## Avoid + +- Fake blurred dashboards. +- Random stock imagery. +- Callouts that point to decorative details. +- Copying another product's UI as the hero proof. diff --git a/plugins/f0d010c/stark/references/web-patterns/asymmetric-grid.md b/plugins/f0d010c/stark/references/web-patterns/asymmetric-grid.md new file mode 100644 index 000000000..034b543bd --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/asymmetric-grid.md @@ -0,0 +1,73 @@ +# Pattern — Asymmetric grid + +Content offset from center, alternating sides, magazine-spread style. + +**When to deploy**: editorial, type-as-hero, glow+grain. Active-bento naturally asymmetric. Industrial-mono can use grid lines but stays uniform. + +## 12-col w/ left rail + +```tsx +
+ +
+ {/* content */} +
+
+``` + +## Alternating featured + +```tsx +{items.map((item, i) => { + const isAlt = i % 2 === 1; + return ( +
+
+ {/* visual */} +
+
+ {/* copy */} +
+
+ ); +})} +``` + +Key: `lg:col-start-N` with `row-start-1` to swap order without HTML reorder. Reading order preserved for screen readers. + +## Off-center hero + +```tsx +
+
+

Hero text starts at column 2, ends at 9

+
+
+``` + +Asymmetric == content NOT in cols 1-12 evenly. Pick 7/9 or 8/10 col span, offset into grid. + +## Magazine multi-column body + +```css +.editorial-body { + column-count: 2; + column-gap: 4rem; + column-rule: 1px solid var(--color-rule); + font-family: var(--font-display); + font-size: 17px; + line-height: 1.6; +} +``` + +Use sparingly — multi-col body rare on web (mobile breaks easily). + +## Avoid + +- Centered everything (max-w-3xl mx-auto) +- Uniform 3-col grids (boring) +- Equal column spans for all features (use 5/7, 4/8, 3/9 mixes) diff --git a/plugins/f0d010c/stark/references/web-patterns/before-after-slider.md b/plugins/f0d010c/stark/references/web-patterns/before-after-slider.md new file mode 100644 index 000000000..d167e8049 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/before-after-slider.md @@ -0,0 +1,29 @@ +# Pattern - Before / after slider + +Use for visual diffs, design audits, image tools, cleanup products, performance before/after, accessibility improvements, and UX redesign proof. + +## Structure + +- Two aligned states with identical dimensions. +- Draggable divider with visible handle and keyboard alternative. +- Labels: before and after, plus what changed. +- Optional issue markers or annotations. +- Text summary below for accessibility and non-pointer users. + +## Implementation notes + +- Use pointer events and keyboard controls for the divider. +- Keep alt text or textual comparison nearby. +- Avoid relying on color alone to show improvement. +- If comparing UI, align baseline, viewport, and data state. + +## Responsive + +- Desktop: horizontal slider works well. +- Mobile: slider can work, but stacked before/after cards are often clearer. + +## Avoid + +- Comparing different content so the improvement is misleading. +- Slider as a gimmick when a simple annotated diff is clearer. +- No keyboard fallback. diff --git a/plugins/f0d010c/stark/references/web-patterns/command-palette.md b/plugins/f0d010c/stark/references/web-patterns/command-palette.md new file mode 100644 index 000000000..03c0b8aef --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/command-palette.md @@ -0,0 +1,35 @@ +# Pattern - Command palette + +Use for expert web apps, devtools, dashboards, editors, admin tools, and desktop-like web surfaces where users need fast navigation and actions. + +## Reference signals + +Shipped products such as Linear and Vercel expose command menus so users can navigate and run common actions with the keyboard while keeping mouse paths available. The key lesson is not the exact modal styling; it is that actions become searchable, contextual, and repeatable. + +## Structure + +- Global shortcut: `Cmd/Ctrl+K`. +- Search input with visible focus and placeholder tied to the current scope. +- Result groups: recent, navigation, create, selected-item actions, settings. +- Each result has label, optional shortcut, icon, and short context. +- Empty state gives a next action, not a tutorial paragraph. +- Dangerous actions require confirmation or move to a secondary flow. + +## Implementation notes + +- Keep command data structured: `id`, `label`, `group`, `keywords`, `shortcut`, `disabledReason`, `run`. +- Support arrow keys, Enter, Escape, and typeahead. +- Show context-aware commands first when an item is selected. +- Do not hide the only path to an action inside the palette. + +## Responsive + +- Desktop: centered overlay or anchored command surface. +- Mobile: full-screen sheet with large hit targets and no hover-only states. + +## Avoid + +- Command palette as decoration on a marketing page. +- Unlabeled icon-only results. +- Fuzzy search that returns destructive actions before navigation. +- Copying Raycast/Linear visuals; borrow action architecture, not skin. diff --git a/plugins/f0d010c/stark/references/web-patterns/connected-animation.md b/plugins/f0d010c/stark/references/web-patterns/connected-animation.md new file mode 100644 index 000000000..47880aca3 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/connected-animation.md @@ -0,0 +1,71 @@ +# Pattern — Connected / shared element animation + +Hero element morphs from gallery tile to detail page. Native `View Transitions API` or Motion `layoutId`. + +**When to deploy**: active-bento (essential), editorial (gallery → detail), type-as-hero (specimen click). + +## Motion `layoutId` + +```tsx +import { motion, AnimatePresence } from "motion/react"; + +function Gallery({ onPick }: { onPick: (id: string) => void }) { + return ( +
+ {items.map((item) => ( + onPick(item.id)} + className="aspect-square rounded-xl bg-stone-200 cursor-pointer" + > + {item.title} + + ))} +
+ ); +} + +function Detail({ id, onClose }: { id: string; onClose: () => void }) { + const item = items.find((i) => i.id === id)!; + return ( + + {item.title} + + ); +} + +// Wrap with + + {selected ? setSelected(null)} /> : null} + +``` + +Same `layoutId` on tile and detail = Motion interpolates position, size, transforms automatically. + +## View Transitions (route-based) + +```css +.tile-cover { + view-transition-name: cover; +} +``` + +When you click + navigate, browser shares element automatically (must have unique `view-transition-name`). + +## Tradeoffs + +| | Motion `layoutId` | View Transitions API | +|---|---|---| +| In-page modal-like | ✅ | Need route | +| Route-based | ❌ | ✅ | +| Spring physics | ✅ | ❌ (CSS animation only) | +| Customization | Full | CSS-only | +| Browser support | All | Chrome/Edge/Safari 18.2+ | +| Performance | JS layout | Native compositor | + +For SPAs with route changes — View Transitions. For in-page detail expansions — Motion `layoutId`. diff --git a/plugins/f0d010c/stark/references/web-patterns/custom-cursor.md b/plugins/f0d010c/stark/references/web-patterns/custom-cursor.md new file mode 100644 index 000000000..7a2d359e2 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/custom-cursor.md @@ -0,0 +1,57 @@ +# Pattern — Custom cursor + +Branded dot follows pointer, scales + labels on hoverable elements ("VIEW", "READ", "PLAY"). Studio-grade detail. + +**When to deploy**: editorial (refined), type-as-hero (cinematic), glow+grain (atmospheric), active-bento (interaction-led). Skip on brutalist (raw) and mobile (no hover). + +```tsx +import { motion, useMotionValue, useSpring } from "motion/react"; +import { useEffect, useState } from "react"; + +export function Cursor() { + const [label, setLabel] = useState(null); + const x = useMotionValue(-100); + const y = useMotionValue(-100); + const sx = useSpring(x, { stiffness: 500, damping: 35 }); + const sy = useSpring(y, { stiffness: 500, damping: 35 }); + const scale = useSpring(1, { stiffness: 400, damping: 25 }); + + useEffect(() => { + const onMove = (e: PointerEvent) => { x.set(e.clientX); y.set(e.clientY); }; + const onOver = (e: PointerEvent) => { + const t = e.target as HTMLElement; + const lbl = t.closest("[data-cursor]")?.getAttribute("data-cursor"); + if (lbl) { setLabel(lbl); scale.set(3); } + else { setLabel(null); scale.set(1); } + }; + window.addEventListener("pointermove", onMove); + window.addEventListener("pointerover", onOver); + return () => { + window.removeEventListener("pointermove", onMove); + window.removeEventListener("pointerover", onOver); + }; + }, [x, y, scale]); + + return ( + + + {label && ( + + {label} + + )} + + + ); +} +``` + +Apply on hoverable elements: ``. + +Hide native cursor: `body { cursor: none }` (offer toggle for accessibility). diff --git a/plugins/f0d010c/stark/references/web-patterns/docs-api-reference-layout.md b/plugins/f0d010c/stark/references/web-patterns/docs-api-reference-layout.md new file mode 100644 index 000000000..7c961c26d --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/docs-api-reference-layout.md @@ -0,0 +1,31 @@ +# Pattern - Docs / API reference layout + +Use for developer docs, API references, SDK pages, integration guides, plugin docs, and CLI docs. + +## Structure + +- Left nav: information architecture and current section. +- Main content: concept, steps, caveats, examples. +- Right rail: on-page headings, version, language, or "copy page" actions. +- Code samples are copyable, labeled, and close to the concept they support. +- Include prerequisites, auth, error cases, rate limits, and environment notes. + +## Interaction + +- Version/language switches preserve context. +- Code snippets have copy feedback. +- Search is available and scoped. +- Related pages appear at the end of the task. + +## Responsive + +- Desktop: 3-column docs layout. +- Tablet: left nav collapses; right rail may disappear. +- Mobile: nav/search in sheet; code blocks scroll within their container. + +## Avoid + +- Marketing hero above every docs page. +- Code samples without expected result. +- Hidden auth/rate-limit requirements. +- Horizontal page overflow from code blocks. diff --git a/plugins/f0d010c/stark/references/web-patterns/empty-state-gallery.md b/plugins/f0d010c/stark/references/web-patterns/empty-state-gallery.md new file mode 100644 index 000000000..f8a26073f --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/empty-state-gallery.md @@ -0,0 +1,27 @@ +# Pattern - Empty state gallery + +Use for products with many surfaces, especially dashboards, settings, onboarding, integrations, editors, and agent tools. + +## Required states + +- Empty: how data arrives and the first useful action. +- Loading: skeleton that preserves layout shape. +- Partial: what is missing and what is still usable. +- Permission: what is blocked, why, and how to request/connect access. +- Error: what failed, whether data is safe, and the recovery action. +- Success: what happened and the next useful step. +- Stale: when data was last updated and how to refresh. + +## Structure + +- Keep the next action close to the state copy. +- Use domain language, not generic "No items yet". +- Make the state visually fit the surface density. +- For repeated-use tools, keep states compact. + +## Avoid + +- Empty states that explain every feature. +- Full-screen celebration for routine success. +- Error copy without a recovery path. +- Loading spinners that collapse the layout. diff --git a/plugins/f0d010c/stark/references/web-patterns/inspector-split-pane.md b/plugins/f0d010c/stark/references/web-patterns/inspector-split-pane.md new file mode 100644 index 000000000..8a02495ba --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/inspector-split-pane.md @@ -0,0 +1,30 @@ +# Pattern - Inspector split pane + +Use for editors, issue trackers, dashboards, agent run viewers, media libraries, and local-first tools where a user selects an object and edits or inspects details without losing list/canvas position. + +## Structure + +- Left or center: stable list, table, board, canvas, timeline, or artifact. +- Right: inspector with selected object title, status, primary action, metadata, state, and history. +- Selection state is visible in both regions. +- Inspector sections are grouped by task: summary, actions, properties, activity, permissions. +- Empty inspector state explains what selecting an item will reveal. + +## Interaction + +- Selecting an item updates the inspector without navigating away. +- Keyboard navigation changes selection. +- Inspector actions are scoped to the selected object. +- High-risk changes need confirmation, undo, or audit trail. + +## Responsive + +- Desktop: persistent right pane. +- Tablet: collapsible pane or resizable split. +- Mobile: detail sheet or route, with a clear back path to preserve list position. + +## Avoid + +- Replacing the list with a detail page for high-frequency triage. +- Putting every field in the inspector with equal weight. +- Decorative cards inside the inspector that slow scanning. diff --git a/plugins/f0d010c/stark/references/web-patterns/keyboard-shortcut-overlay.md b/plugins/f0d010c/stark/references/web-patterns/keyboard-shortcut-overlay.md new file mode 100644 index 000000000..c92ad5a4a --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/keyboard-shortcut-overlay.md @@ -0,0 +1,29 @@ +# Pattern - Keyboard shortcut overlay + +Use for expert tools, editors, desktop-like web apps, dashboards, and command surfaces. + +## Structure + +- Launch with `?` or from help/menu. +- Group shortcuts by task: navigation, creation, selection, editing, view, command menu. +- Show platform-specific modifiers: `Cmd` on macOS, `Ctrl` on Windows/Linux. +- Include context labels when shortcuts only work in a specific surface. +- Search/filter shortcuts when the list is long. + +## Interaction + +- Overlay is dismissible with Escape. +- Shortcuts are discoverable near matching controls when useful. +- Disabled shortcuts explain why they are unavailable. +- Do not trap focus. + +## Responsive + +- Desktop: modal or side sheet. +- Mobile/tablet: use gesture/help sheet; do not imply keyboard-only use. + +## Avoid + +- Shortcut wall with no grouping. +- Keyboard-only features with no mouse/touch path. +- Showing shortcuts that do not exist. diff --git a/plugins/f0d010c/stark/references/web-patterns/lenis-smooth-scroll.md b/plugins/f0d010c/stark/references/web-patterns/lenis-smooth-scroll.md new file mode 100644 index 000000000..4ade69cca --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/lenis-smooth-scroll.md @@ -0,0 +1,82 @@ +# Pattern — Lenis smooth scroll + +Eased momentum scroll. De facto on award sites. + +**When to deploy**: editorial (slow contemplative), type-as-hero (cinematic), glow+grain (atmospheric). **Skip** on brutalist (raw native), industrial-mono (snap), accessibility-first (motion-sensitive users). + +## Install + use + +```bash +npm install lenis +``` + +```tsx +import Lenis from "lenis"; +import { useEffect } from "react"; + +export function App() { + useEffect(() => { + const lenis = new Lenis({ + duration: 1.2, + easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)), + }); + function raf(time: number) { + lenis.raf(time); + requestAnimationFrame(raf); + } + requestAnimationFrame(raf); + return () => lenis.destroy(); + }, []); + // ... +} +``` + +## Tuning + +| Param | Range | Effect | +|---|---|---| +| `duration` | 0.6-1.6 | Total ease time. 1.2 = considered, 0.8 = responsive | +| `lerp` | 0.05-0.15 | Lower = smoother but laggy. Default 0.1 | +| `wheelMultiplier` | 0.8-1.2 | Scroll input scaling | +| `easing` | function | Custom easing | + +## Sync with Motion `useScroll` + +Motion's `useScroll` uses native scroll position, which Lenis hijacks. Use Lenis's events instead: + +```tsx +import { useMotionValue } from "motion/react"; + +const scrollY = useMotionValue(0); +useEffect(() => { + lenis.on("scroll", ({ scroll }) => scrollY.set(scroll)); +}, []); +``` + +## Sync with GSAP ScrollTrigger + +```tsx +import gsap from "gsap"; +import { ScrollTrigger } from "gsap/ScrollTrigger"; +gsap.registerPlugin(ScrollTrigger); + +lenis.on("scroll", ScrollTrigger.update); +gsap.ticker.add((time) => lenis.raf(time * 1000)); +gsap.ticker.lagSmoothing(0); +``` + +## prefers-reduced-motion + +```tsx +const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches; +const lenis = new Lenis({ + duration: reduce ? 0 : 1.2, + smoothWheel: !reduce, +}); +``` + +## Tradeoffs + +- **Pros**: cinematic feel, eases scroll input naturally +- **Cons**: hijacks native scroll, can feel laggy on low-end devices, breaks accessibility for some users, breaks `scroll-snap` and CSS `animation-timeline: view()` +- **Recommendation**: ship with toggle, default off, enable for editorial/cinematic projects only diff --git a/plugins/f0d010c/stark/references/web-patterns/letter-stagger.md b/plugins/f0d010c/stark/references/web-patterns/letter-stagger.md new file mode 100644 index 000000000..038692be1 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/letter-stagger.md @@ -0,0 +1,79 @@ +# Pattern — Letter / word stagger reveal + +Hero text drops in word-by-word or letter-by-letter w/ spring physics. Default page-load motion. + +**When to deploy**: editorial, type-as-hero, glow+grain. Skip on brutalist (instant render). + +## Word-stagger (Motion) + +```tsx +import { motion } from "motion/react"; + +export function StaggerHeadline({ lines }: { lines: string[] }) { + return ( +

+ {lines.map((line, li) => ( + + {line.split(" ").map((word, wi, arr) => ( + + {word} + + ))} + + ))} +

+ ); +} +``` + +Key: parent `block overflow-hidden` clips letterforms during reveal — Awwwards-tier detail. + +## Letter-stagger (heavy) + +```tsx +{word.split("").map((char, ci) => ( + + {char} + +))} +``` + +Letter-stagger only on short hero (5-10 chars). Word-stagger for longer. + +## GSAP SplitText (commercial-grade) + +```tsx +import gsap from "gsap"; +import { SplitText } from "gsap/SplitText"; // free since Webflow acquisition +gsap.registerPlugin(SplitText); + +useEffect(() => { + const split = new SplitText(".headline", { type: "lines, words" }); + gsap.from(split.words, { + y: 100, opacity: 0, + stagger: 0.04, duration: 0.8, + ease: "power3.out", + }); +}, []); +``` + +Use SplitText for: balanced lines, kerning preservation, RTL, complex stacking. diff --git a/plugins/f0d010c/stark/references/web-patterns/magnetic-button.md b/plugins/f0d010c/stark/references/web-patterns/magnetic-button.md new file mode 100644 index 000000000..88df7b156 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/magnetic-button.md @@ -0,0 +1,49 @@ +# Pattern — Magnetic button + +Button attracts cursor within radius. Micro-luxury detail. + +**When to deploy**: editorial, glow+grain, type-as-hero. Use sparingly — 1-2 magnetic CTAs per page. More feels gimmicky. + +```tsx +import { motion, useMotionValue, useSpring, useTransform } from "motion/react"; +import { useRef } from "react"; + +export function MagneticButton({ children }: { children: React.ReactNode }) { + const ref = useRef(null); + const x = useMotionValue(0); + const y = useMotionValue(0); + const sx = useSpring(x, { stiffness: 200, damping: 18 }); + const sy = useSpring(y, { stiffness: 200, damping: 18 }); + + const handleMove = (e: React.PointerEvent) => { + const r = ref.current!.getBoundingClientRect(); + const cx = r.left + r.width / 2; + const cy = r.top + r.height / 2; + const dx = e.clientX - cx; + const dy = e.clientY - cy; + const dist = Math.hypot(dx, dy); + const radius = 80; + if (dist < radius) { + x.set(dx * 0.3); + y.set(dy * 0.3); + } else { + x.set(0); + y.set(0); + } + }; + + return ( + { x.set(0); y.set(0); }} + style={{ x: sx, y: sy }} + className="px-6 py-3 rounded-full bg-ink text-paper text-[13px] tracking-wide hover:bg-oxblood transition-colors" + > + {children} + + ); +} +``` + +Tweak `radius` (60-100px), `0.3` strength (0.15-0.4). Inner content can also magnetize independently (multiplied + smaller strength). diff --git a/plugins/f0d010c/stark/references/web-patterns/marquee.md b/plugins/f0d010c/stark/references/web-patterns/marquee.md new file mode 100644 index 000000000..dfbb0c25d --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/marquee.md @@ -0,0 +1,78 @@ +# Pattern — Marquee band + +Horizontal scrolling text band. Pure CSS, no JS needed. + +**When to deploy**: editorial (philosophical statements), brutalist (manifesto fragments), type-as-hero (specimen showcase), industrial-mono (log stream). + +## CSS-only + +```css +@keyframes marquee { + from { transform: translateX(0); } + to { transform: translateX(-50%); } +} +.marquee-track { + animation: marquee 60s linear infinite; + display: flex; + width: max-content; +} +``` + +```tsx +const items = ["Hand finished", "27 pieces a year", "Made to outlast us"]; + +
+
+ {[0, 1].map((dup) => ( +
+ {items.map((it, i) => ( +
+ + {it} + + +
+ ))} +
+ ))} +
+
+``` + +Duplicate the items twice in track. Animate translateX(-50%). Loop hides the seam. + +## Pause on hover + +```css +.marquee-track:hover { animation-play-state: paused; } +``` + +## Reverse direction + +```css +.marquee-track-reverse { + animation: marquee 60s linear infinite reverse; +} +``` + +## Multi-speed parallax marquees + +Stack 3 marquees at different speeds for editorial depth: + +```tsx +
+ + + + +``` + +## Speed via duration + +`60s` for slow contemplative (editorial). `15-25s` for energetic (active bento). + +## Avoid + +- JS-driven marquees (too heavy, native CSS handles it) +- Very fast marquees (under 10s) — looks twitchy +- Marquees on mobile without `prefers-reduced-motion` respect diff --git a/plugins/f0d010c/stark/references/web-patterns/mesh-gradient.md b/plugins/f0d010c/stark/references/web-patterns/mesh-gradient.md new file mode 100644 index 000000000..54218a791 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/mesh-gradient.md @@ -0,0 +1,75 @@ +# Pattern — Mesh gradient atmosphere + +Multi-stop SVG/CSS radial gradients layered. Creates atmospheric backdrop. + +**When to deploy**: glow+grain (signature), type-as-hero (atmospheric), editorial (subtle), active-bento (per tile). + +## Pure CSS (3-glow stack) + +```tsx +
+
+
+
+
+
+``` + +## Animated drift (Motion) + +```tsx + +``` + +## SVG mesh (more control) + +```tsx + + + + + + + + + + + + + + +``` + +## Track-extracted accent + +For media app (album → page atmosphere derived from cover): + +```tsx +
+``` + +## Don'ts + +- Avoid bright saturated colors (atmosphere needs softness — use `opacity-30` to `opacity-50` + `blur-3xl`) +- Don't stack 5+ glows (3-4 max — more = muddy) +- Don't animate too fast (slow drift 20-40s, not 5s pulse) diff --git a/plugins/f0d010c/stark/references/web-patterns/page-load-curtain.md b/plugins/f0d010c/stark/references/web-patterns/page-load-curtain.md new file mode 100644 index 000000000..be7d2c644 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/page-load-curtain.md @@ -0,0 +1,45 @@ +# Pattern — Page-load curtain + +Paper-colored mask slides off, contents reveal beneath. Sets tone before scroll. + +**When to deploy**: editorial, type-as-hero, glow+grain. Skip on brutalist (raw start) and industrial-mono (terminal already starts with intent). + +```tsx +import { motion, AnimatePresence } from "motion/react"; +import { useEffect, useState } from "react"; + +export function Curtain() { + const [show, setShow] = useState(true); + useEffect(() => { + const t = setTimeout(() => setShow(false), 1100); + return () => clearTimeout(t); + }, []); + return ( + + {show && ( + +
+ + Loading +
+ + )} + + ); +} +``` + +Variants: +- Slide up (origin-bottom, scaleY: 0) +- Slide down (origin-top) +- Diagonal wipe (clip-path inset) +- Split: two halves slide opposite directions +- Letter mask: viewport-filling letterform that scales out + +Pair with Hero `` so content fades in as curtain leaves. diff --git a/plugins/f0d010c/stark/references/web-patterns/parallax-layers.md b/plugins/f0d010c/stark/references/web-patterns/parallax-layers.md new file mode 100644 index 000000000..09b571995 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/parallax-layers.md @@ -0,0 +1,62 @@ +# Pattern — Layered parallax + +Multiple z-layers scroll at different speeds for depth. Editorial / type-as-hero / glow-grain. + +```tsx +import { motion, useScroll, useTransform } from "motion/react"; +import { useRef } from "react"; + +export function ParallaxHero() { + const ref = useRef(null); + const { scrollYProgress } = useScroll({ + target: ref, + offset: ["start start", "end start"], + }); + // Layer speeds + const yBg = useTransform(scrollYProgress, [0, 1], ["0%", "20%"]); + const yMid = useTransform(scrollYProgress, [0, 1], ["0%", "50%"]); + const yFg = useTransform(scrollYProgress, [0, 1], ["0%", "80%"]); + + return ( +
+ + {/* slowest — atmosphere */} +
+ + + {/* mid — illustration */} +
+ + + {/* fastest — type / content */} +

Foreground

+ +
+ ); +} +``` + +## Watch / product layered breakdown + +For product hero (e.g. watch), layer: +1. Background atmosphere (slowest) +2. Watch case (slow) +3. Watch dial (medium) +4. Watch hands (faster) +5. Wordmark (fastest, stays foregrounded) + +## Native CSS scroll-linked (no JS) + +```css +@keyframes parallax-bg { + from { transform: translateY(0); } + to { transform: translateY(20vh); } +} +.parallax-bg { + animation: parallax-bg linear both; + animation-timeline: scroll(); + animation-range: 0 100vh; +} +``` + +Modern browsers — no JS needed. Use for simple parallax. Use Motion `useScroll` for orchestrated multi-layer. diff --git a/plugins/f0d010c/stark/references/web-patterns/permission-trust-matrix.md b/plugins/f0d010c/stark/references/web-patterns/permission-trust-matrix.md new file mode 100644 index 000000000..cbf0cde4d --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/permission-trust-matrix.md @@ -0,0 +1,30 @@ +# Pattern - Permission / trust matrix + +Use for plugin managers, MCP servers, security products, local-first tools, API integrations, deploy settings, admin permissions, and billing/account access. + +## Structure + +- Rows are capabilities, resources, integrations, or scopes. +- Columns show access level, source, reason, status, last used, and action. +- Risk is concrete: read, write, network, shell, secrets, billing, deploy, admin. +- Warnings include why it matters and what the user can do. +- Include audit trail or timestamp for trust-sensitive rows. + +## Interaction + +- Filter by risk, source, status, and recently used. +- Expand a row for exact paths, scopes, scripts, or environment variables. +- Dangerous changes require confirmation and recovery copy. +- "Revoke", "Review", "Allow once", and "Open settings" should be distinct actions. + +## Responsive + +- Desktop: dense table or matrix. +- Mobile: grouped cards with capability and action first. + +## Avoid + +- Vague "secure" badges. +- Hiding the specific resource behind generic labels. +- Alarm colors with no action. +- Showing secrets directly. diff --git a/plugins/f0d010c/stark/references/web-patterns/pricing-comparison-table.md b/plugins/f0d010c/stark/references/web-patterns/pricing-comparison-table.md new file mode 100644 index 000000000..baaed5640 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/pricing-comparison-table.md @@ -0,0 +1,29 @@ +# Pattern - Pricing / plan comparison table + +Use for pricing, checkout, upgrade, plan management, usage-based billing, and subscription settings. + +## Structure + +- Plans are comparable by the same categories. +- Price, billing interval, trial, taxes/fees, cancellation, and renewal terms are close to the CTA. +- Highlight the selected/current plan without hiding alternatives. +- Include feature limits, overages, and support level. +- For existing customers, show current plan and what will change. + +## Interaction + +- Toggle billing interval only when totals remain clear. +- Upgrade/downgrade actions show proration, renewal, and effective date before confirmation. +- Cancellation or downgrade flows need recovery, reason capture, and clear final state. + +## Responsive + +- Desktop: comparison table with sticky plan headers. +- Mobile: plan cards with repeated key limits and a compare details toggle. + +## Avoid + +- Three decorative pricing cards with hidden terms. +- CTA before cost clarity. +- Burying cancellation, renewal, or usage-limit copy. +- Fake urgency. diff --git a/plugins/f0d010c/stark/references/web-patterns/scroll-driven-css.md b/plugins/f0d010c/stark/references/web-patterns/scroll-driven-css.md new file mode 100644 index 000000000..9571c9102 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/scroll-driven-css.md @@ -0,0 +1,87 @@ +# Pattern — Native scroll-driven CSS animation + +`animation-timeline: view()` / `scroll()` — modern browser API for scroll-tied animation w/ zero JS. Chrome 115+, Edge 115+, Safari 26+, Firefox 142+. + +**Use over JS scroll listeners** for: simple reveals, parallax, progress indicators. + +## View timeline (element enters viewport) + +```css +@keyframes fade-up { + from { opacity: 0; transform: translateY(60px); } + to { opacity: 1; transform: translateY(0); } +} + +.reveal-on-scroll { + animation: fade-up linear both; + animation-timeline: view(); + animation-range: entry 0% cover 30%; +} +``` + +`animation-range`: +- `entry` — element starts entering viewport from bottom edge +- `exit` — element starts leaving viewport from top edge +- `cover` — distance element is fully in viewport +- `contain` — distance element is fully contained (small elements) + +Common ranges: +- `entry 0% cover 30%` — fades in as element appears, completes within first 30% of view +- `entry 0% exit 100%` — animation runs entire time element is visible + +## Scroll timeline (page progress) + +```css +.progress-bar { + position: fixed; + top: 0; left: 0; + height: 3px; + background: var(--color-accent); + transform-origin: 0 50%; + animation: progress linear both; + animation-timeline: scroll(root block); +} +@keyframes progress { + from { transform: scaleX(0); } + to { transform: scaleX(1); } +} +``` + +Page-wide scroll progress bar — no JS. + +## Named timelines (advanced) + +```css +.parent { + scroll-timeline-name: --my-timeline; + scroll-timeline-axis: block; +} +.child { + animation: fade linear both; + animation-timeline: --my-timeline; +} +``` + +## Fallback + +Wrap in `@supports`: + +```css +@supports (animation-timeline: view()) { + .reveal-on-scroll { animation: fade-up linear both; ... } +} +@supports not (animation-timeline: view()) { + /* IntersectionObserver fallback or always-visible */ + .reveal-on-scroll { opacity: 1; } +} +``` + +## When to use vs Motion / GSAP + +| Need | Use | +|---|---| +| Element fades in on scroll | Native CSS — `view()` | +| Page scroll progress bar | Native CSS — `scroll()` | +| Scroll-tied complex sequence (5+ pieces) | GSAP ScrollTrigger | +| Spring physics on scroll | Motion `useScroll` | +| Layout animation tied to scroll | Motion `useTransform` | diff --git a/plugins/f0d010c/stark/references/web-patterns/scroll-pinned-section.md b/plugins/f0d010c/stark/references/web-patterns/scroll-pinned-section.md new file mode 100644 index 000000000..7a6062c61 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/scroll-pinned-section.md @@ -0,0 +1,75 @@ +# Pattern — Scroll-pinned section + +Pin viewport, content advances frame-by-frame as scroll progresses. Signature horology / process / feature moment. + +**When to deploy**: editorial (manifesto reveal), type-as-hero (headline morph), industrial-mono (process steps), active-bento (feature tour). 1 per page max. + +## Motion (motion.dev) approach + +```tsx +import { motion, useScroll, useTransform } from "motion/react"; +import { useRef } from "react"; + +export function PinnedExplosion() { + const ref = useRef(null); + const { scrollYProgress } = useScroll({ + target: ref, + offset: ["start start", "end end"], + }); + + // 4-step assembly: each piece appears at progress 0.25, 0.5, 0.75, 1 + const piece1 = useTransform(scrollYProgress, [0, 0.2], [0, 1]); + const piece2 = useTransform(scrollYProgress, [0.2, 0.4], [0, 1]); + const piece3 = useTransform(scrollYProgress, [0.4, 0.6], [0, 1]); + const piece4 = useTransform(scrollYProgress, [0.6, 0.8], [0, 1]); + + return ( +
{/* tall = scroll budget */} +
+
+ {/* base */} + {/* gear set */} + {/* hands */} + {/* case */} +
+
+
+ ); +} +``` + +## GSAP ScrollTrigger alternative (more complex sequences) + +```tsx +import gsap from "gsap"; +import { ScrollTrigger } from "gsap/ScrollTrigger"; +import { useEffect, useRef } from "react"; + +gsap.registerPlugin(ScrollTrigger); + +export function GsapPinned() { + const ref = useRef(null); + useEffect(() => { + const ctx = gsap.context(() => { + const tl = gsap.timeline({ + scrollTrigger: { + trigger: ref.current, + start: "top top", + end: "+=2000", + scrub: 1, + pin: true, + }, + }); + tl.from(".piece-1", { opacity: 0, y: 100 }) + .from(".piece-2", { opacity: 0, y: 100 }, "+=0.5") + .from(".piece-3", { opacity: 0, scale: 0.5 }, "+=0.5"); + }, ref); + return () => ctx.revert(); + }, []); + return
{/* pieces */}
; +} +``` + +Tradeoffs: +- **Motion (motion.dev)** — simpler, React-idiomatic. Best for 2-4 stage reveals. +- **GSAP ScrollTrigger** — best for complex sequences (5+ stages), morph paths, character splitting. diff --git a/plugins/f0d010c/stark/references/web-patterns/sticky-section-markers.md b/plugins/f0d010c/stark/references/web-patterns/sticky-section-markers.md new file mode 100644 index 000000000..2acdac625 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/sticky-section-markers.md @@ -0,0 +1,35 @@ +# Pattern — Sticky § section markers + +Left rail with `sticky` `§ 01` numerals. Editorial signature. + +**When to deploy**: editorial. Optional: type-as-hero, industrial-mono. + +```tsx +export function ManifestoSection() { + return ( +
+
+
+
+ § 01 +

Manifesto

+
+
+
+ {/* content */} +
+
+
+ ); +} +``` + +Key: `sticky top-32` keeps marker visible as user scrolls section content. Each section uses different numeral (§ 01, § 02, § 03). + +Variants: +- Numeral + label ("§ 01 — Manifesto") +- Roman numerals (`I. II. III.`) +- Hash names (`#manifesto`, `#references`) +- Pure numerals (`01.`) + +Combine with section anchor IDs for jump-link nav: `
`. diff --git a/plugins/f0d010c/stark/references/web-patterns/symbol-cycling-hover.md b/plugins/f0d010c/stark/references/web-patterns/symbol-cycling-hover.md new file mode 100644 index 000000000..dd05109c2 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/symbol-cycling-hover.md @@ -0,0 +1,54 @@ +# Pattern — Symbol / glyph cycling on hover + +Text cycles through related glyphs/symbols on hover. Editorial micro-detail. + +**When to deploy**: editorial (numerals), type-as-hero (specimen), industrial-mono (glyph play). + +```tsx +import { useState } from "react"; + +const cycleChars = "01234567ABCDEFGHIJKL"; + +export function GlyphCycle({ value }: { value: string }) { + const [out, setOut] = useState(value); + const [hovering, setHovering] = useState(false); + + const onEnter = () => { + setHovering(true); + let i = 0; + const t = setInterval(() => { + setOut(value.split("").map((c, idx) => { + if (idx < i) return value[idx]; // settled + return cycleChars[Math.floor(Math.random() * cycleChars.length)]; + }).join("")); + if (i++ > value.length) { + clearInterval(t); + setOut(value); + } + }, 60); + }; + const onLeave = () => { setHovering(false); setOut(value); }; + + return ( + + {out} + + ); +} +``` + +Use on metadata: reference numbers (`HC.001.W`), dates, version strings. Adds satisfying micro-interaction. + +## Variant — vertical glyph rotate + +```tsx + + {char} + +``` + +Each char on hover does its own y reveal — cinematic for hero numbers. diff --git a/plugins/f0d010c/stark/references/web-patterns/timeline-run-replay.md b/plugins/f0d010c/stark/references/web-patterns/timeline-run-replay.md new file mode 100644 index 000000000..abb7eca02 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/timeline-run-replay.md @@ -0,0 +1,30 @@ +# Pattern - Timeline / run replay + +Use for AI agents, automation jobs, deployment logs, audit trails, imports, exports, security scans, and long-running tasks. + +## Structure + +- Ordered event list with timestamp, actor/source, state, and artifact. +- Current or selected event has a detail panel. +- Events group into phases: plan, execute, verify, recover, complete. +- Include failures, retries, warnings, and user interventions. +- Artifacts are inspectable: diff, log, screenshot, report, file, command output. + +## Interaction + +- Clicking an event updates detail or scrolls to artifact. +- Filters: errors only, files touched, commands, warnings, user actions. +- Replay mode can step through events but must not hide the full log. +- Stop, retry, resume, and export actions belong near the run state. + +## Responsive + +- Desktop: timeline + detail split pane. +- Mobile: event list with expandable details. + +## Avoid + +- "Working..." with no visible progress. +- Success-only timelines. +- Unclear distinction between agent action and user action. +- Copying terminal aesthetics without useful state. diff --git a/plugins/f0d010c/stark/references/web-patterns/variable-font-hover.md b/plugins/f0d010c/stark/references/web-patterns/variable-font-hover.md new file mode 100644 index 000000000..cd41fa252 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/variable-font-hover.md @@ -0,0 +1,75 @@ +# Pattern — Variable-font axis hover + +`font-variation-settings` shifts on hover (or scroll, or cursor position). Awwwards-tier detail. + +**When to deploy**: editorial (subtle), type-as-hero (signature), industrial-mono (axis play). Pair with variable font that supports axes. + +## Axes by font + +| Font | Axes | +|---|---| +| Newsreader | wght 200-800, opsz 6-72 | +| Inter | wght, slnt | +| Roboto Flex | wght, wdth, opsz, GRAD, slnt, XOPQ, XTRA, YOPQ, YTLC, YTUC, YTAS, YTDE, YTFI | +| Söhne Variable | wght 100-900, opsz | +| Bricolage Grotesque | wdth 75-100, wght 200-800, opsz 12-96 | + +## CSS hover + +```css +.headline { + font-family: "Newsreader", serif; + font-variation-settings: "wght" 400, "opsz" 96; + transition: font-variation-settings 600ms cubic-bezier(0.2, 0, 0, 1); +} +.headline:hover { + font-variation-settings: "wght" 800, "opsz" 144; +} +``` + +## Cursor-Y axis (advanced) + +Map mouse Y position to weight: + +```tsx +import { useEffect, useState } from "react"; + +export function CursorAxisHeadline({ children }: { children: React.ReactNode }) { + const [wght, setWght] = useState(400); + useEffect(() => { + const onMove = (e: PointerEvent) => { + const v = (e.clientY / window.innerHeight) * 600 + 200; // 200-800 + setWght(Math.round(v)); + }; + window.addEventListener("pointermove", onMove); + return () => window.removeEventListener("pointermove", onMove); + }, []); + return ( +

+ {children} +

+ ); +} +``` + +## Scroll-driven axis + +```tsx +const { scrollYProgress } = useScroll(); +const wght = useTransform(scrollYProgress, [0, 1], [400, 800]); + + `"wght" ${w}`) }} +> + {children} + +``` + +## Caveat + +- Variable axes only work if font file supports them — check via Wakamai Fondue (https://wakamaifondue.com) +- Test in Safari (slowest var-axis rendering) +- Don't transition `font-variation-settings` more than 200ms on body text — hurts readability diff --git a/plugins/f0d010c/stark/references/web-patterns/view-transitions.md b/plugins/f0d010c/stark/references/web-patterns/view-transitions.md new file mode 100644 index 000000000..68dc3c7f6 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-patterns/view-transitions.md @@ -0,0 +1,82 @@ +# Pattern — View Transitions API + +Native browser API for SPA route transitions + shared element animations. Replaces FLIP / many JS animation patterns. + +**Browser**: Chrome, Edge, Safari 18.2+, Firefox 142+. Wide support 2026. + +## Basic route transition + +```tsx +const navigate = (href: string) => { + if (!document.startViewTransition) { + location.href = href; + return; + } + document.startViewTransition(() => { + history.pushState({}, "", href); + // trigger React state update or routing + window.dispatchEvent(new PopStateEvent("popstate")); + }); +}; +``` + +## Customize transition + +```css +::view-transition-old(root), +::view-transition-new(root) { + animation-duration: 600ms; + animation-timing-function: cubic-bezier(0.2, 0, 0, 1); +} + +@keyframes slide-from-right { + from { transform: translateX(100%); } +} +::view-transition-new(root) { + animation-name: slide-from-right; +} +::view-transition-old(root) { + animation-name: slide-from-right; + animation-direction: reverse; +} +``` + +## Shared element transition + +Mark elements w/ unique `view-transition-name`: + +```css +.album-cover { + view-transition-name: album-cover; +} +``` + +When you click a list tile + navigate to detail page where same element exists with same `view-transition-name`, browser interpolates between them. Hero animation for free. + +## Next 15 integration + +```tsx +"use client"; +import { unstable_ViewTransition as ViewTransition } from "react"; + + +
your route content
+ +``` + +Or use `next/transition` (Next 15.2+): + +```tsx +import { useRouter } from "next/navigation"; + +const router = useRouter(); +router.push("/detail", { scroll: false }); +// View Transition fires automatically on route change +``` + +## Tradeoffs + +- **Pros**: native, declarative, zero-JS for the animation, shared-element automatic +- **Cons**: limited customization beyond CSS, no spring physics (use Motion for those) +- **Use for**: route changes, list-to-detail, tab switches +- **Don't use for**: continuous interactions (hover, drag, scroll-tied) — use Motion instead diff --git a/plugins/f0d010c/stark/references/web-svg-illustration.md b/plugins/f0d010c/stark/references/web-svg-illustration.md new file mode 100644 index 000000000..925a58159 --- /dev/null +++ b/plugins/f0d010c/stark/references/web-svg-illustration.md @@ -0,0 +1,123 @@ +# Web SVG / CSS Illustration — No-Image Asset Generation + +The model must NEVER write `` or `via.placeholder.com` URLs. Instead generate visuals. + +## Strategy 1 — Generated SVG illustration + +For products / objects (watches, devices, abstract forms): + +```tsx +// Build bespoke SVG/CSS product visuals inline instead of linking placeholder images. + + + {/* layered shapes */} + +``` + +Examples of CSS/SVG-rendered objects: +- **Watches** — case + dial + hands as concentric circles + lines +- **Phones / devices** — rounded-rect frames + screen + speakers +- **Cars** — silhouette path + wheel circles + accent lines +- **Coffee cups** — curved paths + handle ellipse + shadow +- **Type specimens** — single mega-letter with frame + +## Strategy 2 — Mesh gradient as hero + +When hero needs atmospheric visual but not an object: + +```tsx +
+
+
+
+``` + +## Strategy 3 — Type-as-image + +Treat large characters as primary visual: + +```tsx +
+ + R + +
+ Reference +
+
+``` + +## Strategy 4 — Geometric abstract layered shapes + +For tech / abstract / non-representational: + +```tsx +
+ {/* Big circle */} +
+ {/* Orbital ring */} +
+ {/* Diagonal stripe */} +
+ {/* Grain */} +
+
+``` + +## Strategy 5 — Procedural patterns + +For backgrounds: + +```tsx +{/* Repeating paper texture */} +
')" }} +/> +``` + +```tsx +{/* Diagonal stripe pattern */} +
+``` + +## Strategy 6 — Inline SVG noise + +```tsx +
+``` + +```css +.noise-overlay { + position: absolute; + inset: 0; + pointer-events: none; + opacity: 0.05; + background-image: url("data:image/svg+xml;utf8,"); +} +``` + +## When you absolutely need an image + +If the user provides actual product photos or insists on imagery: +- Use user-provided, licensed, generated, or code-rendered imagery that supports the product job. +- Add `loading="lazy"` always +- Use `` w/ multiple sources for art-direction +- ALT text mandatory + +But default = generate the visual yourself. + +## Don'ts + +- `` — show what you can't deliver +- `via.placeholder.com/600x400` — visible filler +- `https://images.unsplash.com/photo-...` — generic stock that screams template +- "Image goes here" — placeholder text +- Empty divs with `bg-gray-200` named "image" — give it character + +## Reference example + +Good generated product visuals are full no-image illustrations: layered SVG/CSS shapes, meaningful labels, gradients or texture when needed, and no external placeholder images. diff --git a/plugins/f0d010c/stark/scripts/detect_platform.py b/plugins/f0d010c/stark/scripts/detect_platform.py new file mode 100644 index 000000000..cb4775f13 --- /dev/null +++ b/plugins/f0d010c/stark/scripts/detect_platform.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 +""" +detect_platform.py — Heuristic platform detector for design-router. + +Reads a request string from --text or stdin, returns one of: + web | windows | apple | android | cross-platform | ambiguous + +Used by design-router skill as a deterministic fallback when LLM dispatch is uncertain. + +Usage: + echo "Build a Settings screen for our Win11 app with Mica" | python detect_platform.py + python detect_platform.py --text "I need a SwiftUI tab bar with Liquid Glass" +""" + +from __future__ import annotations +import argparse +import re +import sys + +SIGNALS: dict[str, list[str]] = { + "windows": [ + r"\bwinui\b", r"\bxaml\b", r"\bwpf\b", r"\bwinapp\s*sdk\b", + r"\bfluent\b", r"\bmica\b", r"\bacrylic\b", r"\bwindows\b", + r"\bwin11\b", r"\bwin12\b", r"\bsegoe\b", r"\bmicrosoft store\b", + r"\bpowertoys\b", r"\b\.xaml\b", r"\bcommunitytoolkit\b", + r"\bnavigationview\b", r"\bsettingscard\b", + ], + "apple": [ + r"\bswiftui\b", r"\buikit\b", r"\bappkit\b", r"\bmacos\b", + r"\bipados?\b", r"\bios\b", r"\biphone\b", r"\bipad\b", + r"\bliquid\s*glass\b", r"\bsf\s*symbols?\b", r"\bsf\s*pro\b", + r"\b\.swift\b", r"\bnavigationsplitview\b", r"\btabview\b", + r"\bhig\b", r"\bapp\s*store\b", r"\bxcode\b", + r"\btahoe\b", r"\bcupertino\b", r"\bcatalyst\b", + r"\bvisionos\b", r"\bwatchos\b", + ], + "android": [ + r"\bjetpack compose\b", r"\bcompose\b(?!\s*[- ]?multiplatform)", + r"\bmaterial 3\b", r"\bmaterial you\b", r"\bm3 expressive\b", + r"\bmaterial 3 expressive\b", r"\bm3e\b", + r"\bandroid\b", r"\bpixel\b(?!\s*art)", r"\bplay store\b", + r"\b\.kt\b", r"\b\.kts\b", r"\bkotlin\b", + r"\bnavigationsuitescaffold\b", r"\bpredictive back\b", + ], + "web": [ + r"\breact\b", r"\bnext(?:\.js)?\b", r"\bnextjs\b", + r"\bastro\b", r"\bsveltekit\b", r"\bsvelte\b", + r"\bvue\b", r"\bsolid(?:\s*js)?\b", r"\bqwik\b", + r"\btailwind\b", r"\bshadcn\b", r"\bradix\b", + r"\blanding page\b", r"\bmarketing site\b", r"\bweb app\b", + r"\bdashboard\b", r"\bhero section\b", + r"\b\.tsx\b", r"\b\.jsx\b", r"\b\.html\b", r"\b\.svelte\b", r"\b\.vue\b", + r"\bcss\b", r"\bhtml\b", + ], + "cross-platform": [ + r"\btauri\b", r"\belectron\b", r"\bflutter\b", + r"\breact native\b", r"\brn\b", r"\bexpo\b", + r"\bcompose[- ]multiplatform\b", r"\bcmp\b", + r"\buno platform\b", r"\bavalonia\b", r"\bmaui\b", + r"\bcross[\s-]?platform\b", r"\ball platforms\b", + r"\bone codebase\b", + ], +} + + +def score(text: str) -> dict[str, int]: + text = text.lower() + return { + platform: sum(1 for pat in patterns if re.search(pat, text)) + for platform, patterns in SIGNALS.items() + } + + +def detect(text: str) -> str: + scores = score(text) + nonzero = {p: s for p, s in scores.items() if s > 0} + if not nonzero: + return "ambiguous" + + # Cross-platform wins only with an explicit multi-platform signal. + if "cross-platform" in nonzero: + return "cross-platform" + + named_platforms = [platform for platform in ("windows", "apple", "android") if platform in nonzero] + if len(named_platforms) > 1: + return "cross-platform" + + # Otherwise: highest score + top = max(nonzero.items(), key=lambda kv: kv[1]) + runner_up = sorted(nonzero.values(), reverse=True) + if len(runner_up) > 1 and runner_up[0] - runner_up[1] < 2: + if len(named_platforms) == 1: + return named_platforms[0] + top_platforms = [platform for platform, value in nonzero.items() if value == runner_up[0]] + if len(top_platforms) == 1: + return top_platforms[0] + return "ambiguous" + return top[0] + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--text", help="Request text. If omitted, reads from stdin.") + ap.add_argument("--verbose", action="store_true", help="Show per-platform scores.") + args = ap.parse_args() + + text = args.text if args.text else sys.stdin.read() + if not text.strip(): + print("ambiguous") + return 0 + + if args.verbose: + for platform, s in sorted(score(text).items(), key=lambda kv: -kv[1]): + print(f" {platform:>16}: {s}", file=sys.stderr) + + print(detect(text)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/plugins/f0d010c/stark/scripts/token_export.py b/plugins/f0d010c/stark/scripts/token_export.py new file mode 100644 index 000000000..a683d8e60 --- /dev/null +++ b/plugins/f0d010c/stark/scripts/token_export.py @@ -0,0 +1,474 @@ +#!/usr/bin/env python3 +""" +token_export.py — Translate a DTCG W3C token JSON into platform outputs. + +Usage: + python token_export.py --input tokens.json --target tailwind --output theme.css + python token_export.py --input tokens.json --target compose --output Theme.kt + python token_export.py --input tokens.json --target swiftui --output DesignSystem.swift + python token_export.py --input tokens.json --target winui --output Resources.xaml + python token_export.py --input tokens.json --target css --output theme.css + +Targets: + tailwind - Tailwind v4 @theme block + css - :root CSS custom properties + compose - Compose Material3 ColorScheme + Typography + swiftui - Swift extension on Color + Font + winui - WinUI 3 ResourceDictionary XAML + +Tokens follow W3C Design Tokens Community Group format. Resolves $value references like {color.brand.primary}. +""" + +from __future__ import annotations +import argparse +import json +import re +import sys +from pathlib import Path +from typing import Any + + +REF = re.compile(r"\{([^}]+)\}") + + +def load_tokens(path: Path) -> dict[str, Any]: + return json.loads(path.read_text(encoding="utf-8")) + + +def flatten(node: Any, prefix: str = "", inherited_type: str | None = None) -> dict[str, dict[str, Any]]: + """Walk DTCG tree, return {dotted.path: {$value, $type, ...}}.""" + out: dict[str, dict[str, Any]] = {} + if isinstance(node, dict): + current_type = node.get("$type", inherited_type) + if "$value" in node: + token = dict(node) + if current_type and "$type" not in token: + token["$type"] = current_type + out[prefix] = token + return out + for key, child in node.items(): + if key.startswith("$"): + continue + new_prefix = f"{prefix}.{key}" if prefix else key + out.update(flatten(child, new_prefix, current_type)) + return out + + +def resolve(value: Any, all_tokens: dict[str, dict[str, Any]], visited: set[str] | None = None) -> Any: + if isinstance(value, dict): + return {k: resolve(v, all_tokens, visited) for k, v in value.items()} + if isinstance(value, list): + return [resolve(v, all_tokens, visited) for v in value] + if not isinstance(value, str): + return value + + visited = visited or set() + full_ref = REF.fullmatch(value) + if full_ref: + ref_path = full_ref.group(1) + if ref_path not in all_tokens: + return value + if ref_path in visited: + raise ValueError(f"Circular token reference detected: {' -> '.join([*visited, ref_path])}") + return resolve(all_tokens[ref_path]["$value"], all_tokens, visited | {ref_path}) + + def replace_reference(match: re.Match[str]) -> str: + ref_path = match.group(1) + if ref_path not in all_tokens: + return match.group(0) + if ref_path in visited: + raise ValueError(f"Circular token reference detected: {' -> '.join([*visited, ref_path])}") + resolved = resolve(all_tokens[ref_path]["$value"], all_tokens, visited | {ref_path}) + return str(resolved) + + return REF.sub(replace_reference, value) + + +def kebab(s: str) -> str: + return s.replace(".", "-").replace("_", "-") + + +def strip_category(path: str, category: str) -> str: + prefix = f"{category}." + if path == category: + return path + if path.startswith(prefix): + return path[len(prefix):] + return path + + +def tailwind_color_name(path: str) -> str: + if path.startswith("color-dark."): + return "dark." + path[len("color-dark."):] + return strip_category(path, "color") + + +def camel(s: str) -> str: + parts = [part for part in re.split(r"[._-]+", s) if part] + if not parts: + return "" + return parts[0] + "".join(part[:1].upper() + part[1:] for part in parts[1:]) + + +def numeric_token_value(value: Any, default: float) -> float: + if isinstance(value, (int, float)): + return float(value) + if isinstance(value, str): + match = re.search(r"-?\d+(?:\.\d+)?", value) + if match: + return float(match.group(0)) + return default + + +def line_height_value(value: Any, font_size: float) -> float: + if isinstance(value, (int, float)): + numeric = float(value) + return numeric * font_size if 0 < numeric < 4 else numeric + if isinstance(value, str): + stripped = value.strip() + match = re.search(r"-?\d+(?:\.\d+)?", stripped) + if match: + numeric = float(match.group(0)) + if not re.search(r"[a-zA-Z%]", stripped) and 0 < numeric < 4: + return numeric * font_size + return numeric + return font_size + + +def swift_weight(value: Any) -> str: + if isinstance(value, (int, float)): + if value >= 800: + return ".heavy" + if value >= 700: + return ".bold" + if value >= 600: + return ".semibold" + if value >= 500: + return ".medium" + if value <= 300: + return ".light" + return ".regular" + + normalized = str(value).strip().lower().replace(" ", "") + mapping = { + "thin": ".thin", + "extralight": ".ultraLight", + "ultralight": ".ultraLight", + "light": ".light", + "regular": ".regular", + "normal": ".regular", + "medium": ".medium", + "semibold": ".semibold", + "demibold": ".semibold", + "bold": ".bold", + "extrabold": ".heavy", + "black": ".black", + "heavy": ".heavy", + } + return mapping.get(normalized, ".regular") + + +# ---- Tailwind v4 ---------------------------------------------------------- + +def export_tailwind(tokens: dict[str, dict[str, Any]]) -> str: + lines = ["@theme {"] + for path, tok in tokens.items(): + t = tok.get("$type") + v = resolve(tok["$value"], tokens) + if t == "color": + lines.append(f" --color-{kebab(tailwind_color_name(path))}: {v};") + elif t == "dimension": + spacing_path = strip_category(strip_category(path, "spacing"), "space") + lines.append(f" --spacing-{kebab(spacing_path)}: {v};") + elif t == "duration": + lines.append(f" --duration-{kebab(strip_category(path, 'duration'))}: {v};") + elif t == "typography" and isinstance(v, dict): + name = kebab(strip_category(strip_category(path, "typography"), "type")) + if "fontFamily" in v: + lines.append(f" --font-{name}: {v['fontFamily']};") + if "fontSize" in v: + lines.append(f" --text-{name}: {v['fontSize']};") + lines.append("}") + return "\n".join(lines) + "\n" + + +# ---- Plain CSS ------------------------------------------------------------ + +def export_css(tokens: dict[str, dict[str, Any]]) -> str: + lines = [":root {"] + for path, tok in tokens.items(): + t = tok.get("$type") + v = resolve(tok["$value"], tokens) + if t in ("color", "dimension", "duration"): + lines.append(f" --{kebab(path)}: {v};") + lines.append("}") + return "\n".join(lines) + "\n" + + +# ---- SwiftUI -------------------------------------------------------------- + +def hex_to_swift_color(h: str) -> str: + h = h.lstrip("#") + if len(h) == 6: + r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16) + return f"Color(red: {r/255:.3f}, green: {g/255:.3f}, blue: {b/255:.3f})" + if len(h) == 8: + r, g, b, a = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16), int(h[6:8], 16) + return f"Color(red: {r/255:.3f}, green: {g/255:.3f}, blue: {b/255:.3f}, opacity: {a/255:.3f})" + return f"/* unparsed: {h} */ Color.gray" + + +def swift_font_expr(value: dict[str, Any]) -> str: + family = value.get("fontFamily") + size = numeric_token_value(value.get("fontSize"), 16) + weight = swift_weight(value.get("fontWeight", "regular")) + + if family: + return f'Font.custom("{family}", size: {size:g}).weight({weight})' + return f"Font.system(size: {size:g}, weight: {weight})" + + +def export_swiftui(tokens: dict[str, dict[str, Any]]) -> str: + lines = ["import SwiftUI", "", "extension Color {"] + for path, tok in tokens.items(): + if tok.get("$type") != "color": + continue + v = str(resolve(tok["$value"], tokens)) + var = camel(path) + if v.startswith("#"): + lines.append(f" static let {var} = {hex_to_swift_color(v)}") + elif v.startswith("Color"): + lines.append(f" static let {var} = {v}") + else: + lines.append(f" // unhandled: {path} = {v}") + lines.append("}") + + typography_lines = ["", "extension Font {"] + typography_count = 0 + for path, tok in tokens.items(): + if tok.get("$type") != "typography": + continue + v = resolve(tok["$value"], tokens) + if not isinstance(v, dict): + continue + typography_count += 1 + typography_lines.append(f" static let {camel(path)} = {swift_font_expr(v)}") + + if typography_count: + typography_lines.append("}") + lines.extend(typography_lines) + + line_height_lines = ["", "extension CGFloat {"] + line_height_count = 0 + for path, tok in tokens.items(): + if tok.get("$type") != "typography": + continue + v = resolve(tok["$value"], tokens) + if not isinstance(v, dict) or "lineHeight" not in v: + continue + line_height_count += 1 + font_size = numeric_token_value(v.get("fontSize"), 16) + line_height = line_height_value(v.get("lineHeight"), font_size) + line_height_lines.append(f" static let {camel(path)}LineHeight: CGFloat = {line_height:g}") + if line_height_count: + line_height_lines.append("}") + lines.extend(line_height_lines) + return "\n".join(lines) + "\n" + + +# ---- Compose -------------------------------------------------------------- + +def hex_to_compose(h: str) -> str: + h = h.lstrip("#") + if len(h) == 6: + return f"Color(0xFF{h.upper()})" + if len(h) == 8: + return f"Color(0x{h[6:8].upper()}{h[0:6].upper()})" + return f"/* unparsed: {h} */ Color.Gray" + + +def css_hex_to_xaml(h: str) -> str: + h = h.strip() + if re.fullmatch(r"#[0-9A-Fa-f]{8}", h): + return f"#{h[7:9]}{h[1:7]}".upper() + if re.fullmatch(r"#[0-9A-Fa-f]{6}", h): + return h.upper() + return h + + +def compose_font_weight(value: Any) -> str: + if isinstance(value, (int, float)): + return f"FontWeight.W{int(value)}" + normalized = str(value).strip().lower().replace(" ", "") + mapping = { + "thin": "FontWeight.Thin", + "extralight": "FontWeight.ExtraLight", + "light": "FontWeight.Light", + "regular": "FontWeight.Normal", + "normal": "FontWeight.Normal", + "medium": "FontWeight.Medium", + "semibold": "FontWeight.SemiBold", + "demibold": "FontWeight.SemiBold", + "bold": "FontWeight.Bold", + "extrabold": "FontWeight.ExtraBold", + "black": "FontWeight.Black", + } + return mapping.get(normalized, "FontWeight.Normal") + + +def compose_text_style_expr(value: dict[str, Any]) -> str: + size = numeric_token_value(value.get("fontSize"), 16) + line_height = line_height_value(value.get("lineHeight"), size) + weight = compose_font_weight(value.get("fontWeight", "regular")) + return f"TextStyle(fontSize = {size:g}.sp, lineHeight = {line_height:g}.sp, fontWeight = {weight})" + + +def compose_typography_slot(path: str) -> str | None: + name = path.split(".")[-1] + mapping = { + "display-large": "displayLarge", + "display-medium": "displayMedium", + "display-small": "displaySmall", + "headline-large": "headlineLarge", + "headline-medium": "headlineMedium", + "headline-small": "headlineSmall", + "title-large": "titleLarge", + "title-medium": "titleMedium", + "title-small": "titleSmall", + "body-large": "bodyLarge", + "body-medium": "bodyMedium", + "body-small": "bodySmall", + "label-large": "labelLarge", + "label-medium": "labelMedium", + "label-small": "labelSmall", + } + return mapping.get(name) + + +def export_compose(tokens: dict[str, dict[str, Any]]) -> str: + lines = [ + "package design.tokens", + "", + "import androidx.compose.material3.ColorScheme", + "import androidx.compose.material3.Typography", + "import androidx.compose.material3.lightColorScheme", + "import androidx.compose.ui.graphics.Color", + "import androidx.compose.ui.text.TextStyle", + "import androidx.compose.ui.text.font.FontWeight", + "import androidx.compose.ui.unit.dp", + "import androidx.compose.ui.unit.sp", + "", + "object DesignTokens {", + ] + for path, tok in tokens.items(): + t = tok.get("$type") + v = resolve(tok["$value"], tokens) + var = camel(path) + if t == "color": + v_str = str(v) + if v_str.startswith("#"): + lines.append(f" val {var} = {hex_to_compose(v_str)}") + elif t == "dimension": + v_str = str(v).replace("px", "").replace("dp", "").replace("sp", "") + try: + _ = float(v_str) + lines.append(f" val {var} = {v_str}.dp") + except ValueError: + pass + elif t == "typography" and isinstance(v, dict): + lines.append(f" val {var} = {compose_text_style_expr(v)}") + + color_scheme_args: list[str] = [] + color_scheme_slots = { + "primary", "onPrimary", "primaryContainer", "onPrimaryContainer", + "inversePrimary", "secondary", "onSecondary", "secondaryContainer", + "onSecondaryContainer", "tertiary", "onTertiary", "tertiaryContainer", + "onTertiaryContainer", "background", "onBackground", "surface", + "onSurface", "surfaceVariant", "onSurfaceVariant", "surfaceTint", + "inverseSurface", "inverseOnSurface", "error", "onError", + "errorContainer", "onErrorContainer", "outline", "outlineVariant", + "scrim", + } + for path, tok in tokens.items(): + if tok.get("$type") != "color" or not path.startswith("color."): + continue + slot = camel(strip_category(path, "color")) + if slot in color_scheme_slots: + color_scheme_args.append(f" {slot} = {camel(path)}") + if color_scheme_args: + lines.append("") + lines.append(" val colorScheme: ColorScheme = lightColorScheme(") + lines.append(",\n".join(color_scheme_args)) + lines.append(" )") + + typography_assignments: list[str] = [] + for path, tok in tokens.items(): + if tok.get("$type") != "typography": + continue + slot = compose_typography_slot(path) + if slot: + typography_assignments.append(f" {slot} = {camel(path)}") + if typography_assignments: + lines.append("") + lines.append(" val typography = Typography(") + lines.append(",\n".join(typography_assignments)) + lines.append(" )") + lines.append("}") + return "\n".join(lines) + "\n" + + +# ---- WinUI --------------------------------------------------------------- + +def export_winui(tokens: dict[str, dict[str, Any]]) -> str: + lines = [ + '', + ] + for path, tok in tokens.items(): + t = tok.get("$type") + v = resolve(tok["$value"], tokens) + key = path.replace(".", "_").replace("-", "_") + v_str = str(v) + if t == "color" and v_str.startswith("#"): + lines.append(f' {css_hex_to_xaml(v_str)}') + lines.append(f' ') + elif t == "dimension": + num = v_str.replace("px", "").replace("dp", "") + try: + _ = float(num) + lines.append(f' {num}') + except ValueError: + pass + lines.append("") + return "\n".join(lines) + "\n" + + +# ---- Main ----------------------------------------------------------------- + +EXPORTERS = { + "tailwind": export_tailwind, + "css": export_css, + "swiftui": export_swiftui, + "compose": export_compose, + "winui": export_winui, +} + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--input", required=True, type=Path) + ap.add_argument("--target", required=True, choices=list(EXPORTERS.keys())) + ap.add_argument("--output", required=True, type=Path) + args = ap.parse_args() + + raw = load_tokens(args.input) + flat = flatten(raw) + out = EXPORTERS[args.target](flat) + args.output.write_text(out, encoding="utf-8") + print(f"wrote {args.output} ({len(out)} chars, {len(flat)} tokens)", file=sys.stderr) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/plugins/f0d010c/stark/skills/android-design/SKILL.md b/plugins/f0d010c/stark/skills/android-design/SKILL.md new file mode 100644 index 000000000..e7f9e7349 --- /dev/null +++ b/plugins/f0d010c/stark/skills/android-design/SKILL.md @@ -0,0 +1,154 @@ +--- +name: android-design +description: Use when the user asks for an Android app, Compose UI, Material 3, Material You, Pixel-style app, foldable adaptive layout, React Native Android, Flutter Android, Compose Multiplatform, or any Android deliverable. Builds Android 16+ apps across system-like Compose, branded Compose, React Native, Flutter, and Compose Multiplatform. ALWAYS ask which track first. SKIP when the target is only iOS, Windows, or web-in-browser. +--- + +# android-design — pick the track first + +Android has multiple stacks with different visual ceilings. **Ask the user which one before any code.** + +## Step 0 (MANDATORY) — Ask the user which track + +> Which track for this app? +> +> **1. System-like native (Jetpack Compose + Material 3 Expressive strict)** — feels like Pixel Launcher, Google Calendar, Settings. Best for: utilities, system tools, productivity. Spring physics, shape morphing, wavy progress, dynamic color (Material You). Examples: Read You, Androidify sample, Files by Google. +> +> **2. Branded native (Compose + custom Material theme)** — native chrome (M3E motion, predictive back, edge-to-edge) but bespoke content surface (custom typography, hero atmospheres, magazine layouts). Visual ceiling: high. Examples: Fitbit redesign, Google Calendar's editorial moments, Niantic apps. +> +> **3. React Native (New Architecture + Fabric + Hermes)** — real Android views, decent native feel, JavaScript codebase, cross-platform with iOS. Material themable but won't get spring physics or shape morphing without manual work. Examples: Discord mobile, Coinbase, Microsoft Office. +> +> **4. Flutter** — Skia-painted custom rendering. Cross-platform single codebase. Lags Material updates (no M3 Expressive parity, no real dynamic color). Visual ceiling: high if you ship your own design language; weak if mimicking Material. Examples: Google Pay, BMW My BMW, Toyota. +> +> **5. Compose Multiplatform (1.8+)** — same Compose code, runs Android + iOS + Desktop + Web (Wasm experimental). Native on Android, Material-look on iOS (you must Cupertino-skin or accept). Best for: Kotlin shop wanting cross-platform from one codebase. +> +> Which? Or describe priorities (Play Store launch, cross-platform reach, brand vs Material fit) and I'll pick. + +If brief gives strong signal (e.g. "Pixel-style camera" → 1; "cross-platform with React team" → 3; "Kotlin shop, ship to all platforms" → 5), state your pick + reasoning in one sentence. If ambiguous, ask. + +## Step 0b — Once picked, route + +| Track | Reference docs | Default stack | +|---|---|---| +| 1. System-like Compose | `../../references/material3-expressive.md` | Compose BOM 2026.04 + Material3 1.4 + adaptive layouts strict | +| 2. Branded Compose | Same as 1 | Same as 1 + custom display font + hero atmospheres + bespoke surfaces | +| 3. React Native | `../../references/web-fonts.md` + cross-platform docs | RN 0.78+ New Arch + Expo Router | +| 4. Flutter | None for native fidelity | Flutter 3+ stable | +| 5. Compose Multiplatform | `../../references/material3-expressive.md` | CMP 1.8 stable + shared Compose | + +For tracks 3 and 4: web/cross-platform anti-slop rules apply. Read web references. + +State the chosen aesthetic direction and track in one sentence at top of response. + +## Step 0c — UI decision brief + +Before code, read: + +- `../../references/ui-patterns/surface-taxonomy.md` +- `../../references/ui-patterns/ui-decision-brief.md` +- `../../references/ui-patterns/visual-hierarchy.md` +- `../../references/ui-patterns/motion-budget.md` + +Write the UI decision brief and adapt it to the chosen Android track. Compact screens need thumb-reachable primary actions, sheets, edge-to-edge, and adaptive navigation; tablets/foldables need list-detail or supporting panes; operational tools should stay dense and scannable while preserving Material 3 Expressive motion, dynamic color, and predictive back. + +## Step 1 — Material 3 Expressive default (only if track 1 or 2) + +Launched at I/O 2025. Default for Pixel 10 / Android 16 QPR1. Generated UI must adopt: + +- **Spring physics on every motion** — `MotionScheme.expressive()`. Never `FastOutSlowIn` on M3E surfaces. +- **Shape morphing** — 35 new shapes (squircle, pill, cookie, clover). Use `MaterialShapes.Cookie4Sided`, `Pill`, etc. Buttons/chips/loaders morph between states. +- **Emphasized typography** — bigger, heavier headlines. Use `MaterialTheme.typography.displayLarge` with intent. +- **New components**: + - `FloatingToolbar` (pill-shaped, drifts with content) + - `ButtonGroup` / `SplitButton` + - `FloatingActionButtonMenu` + - `ContainedLoadingIndicator` (cycles through M3E shapes) + - **Wavy progress** — `LinearWavyProgressIndicator`, `CircularWavyProgressIndicator` with variable amplitude + - Large/Small/XL button sizes +- **Tonal elevation** — surface tone shifts, never `Modifier.shadow()` for elevation +- **Dynamic color (Material You)** — `dynamicColorScheme()` from wallpaper on Android 12+ + +Read `../../references/material3-expressive.md` for the M3E adoption checklist. + +## Step 2 — Compose currency (BOM 2026.04.01) + +```kotlin +implementation(platform("androidx.compose:compose-bom:2026.04.01")) +implementation("androidx.compose.material3:material3:1.4.0") +// or for shape-morphing chips: +implementation("androidx.compose.material3:material3:1.5.0-alpha18") +``` + +Use: +- `currentWindowAdaptiveInfo()` + `NavigationSuiteScaffold` (auto-swaps Bar/Rail/Drawer by WindowSizeClass) +- `ListDetailPaneScaffold`, `SupportingPaneScaffold`, `NavigableListDetailPaneScaffold` +- `SharedTransitionLayout { ... }` for shared element transitions (stable) +- `PredictiveBackHandler` / `BackHandler` — **mandatory** on Android 16, default ON Android 15+ +- `LookaheadAnimationVisualDebugging` for inspecting bounds during dev + +## Step 3 — Edge-to-edge is mandatory + +Android 16 (API 36) deprecated `windowOptOutEdgeToEdgeEnforcement`. Every screen: +- Wraps in `Scaffold` with content padding from insets +- Uses `WindowInsets.systemBars`, `.statusBars`, `.navigationBars` +- Predictive back must be wired +- Status bar color cannot be set opaque — banned on Android 16 + +## Step 4 — Adaptive layouts + +- **Compact** (phone portrait) → `NavigationBar` (3–5 items) +- **Medium** (foldable inner / tablet portrait) → `NavigationRail` +- **Expanded** (tablet landscape / desktop) → `NavigationDrawer` (modal or permanent) + `ListDetailPaneScaffold` +- **Foldables**: handle tabletop / book postures via `WindowInfoTracker` + +## Step 5 — Typography & icons + +- **Default body**: Roboto Flex (variable). Headlines: per-app brand expression — but stay within M3E weight/size scale. +- **Material Symbols** (variable axes: weight, fill, grade, optical size) — never FontAwesome/Lucide. +- Get Material Symbols from https://fonts.google.com/icons + +## Step 6 — Anti-slop ban list (Android-specific) + +- iOS-style top nav bars / chevron-back headers +- Hamburger drawer when `NavigationBar` (3–5 items) or `NavigationRail` fits +- Hard `Modifier.shadow(elevation = 8.dp)` — use `tonalElevation` on `Surface` instead +- Custom back stacks ignoring system back / predictive animation +- Opaque colored status bars — banned on Android 16 +- Bottom sheets without drag handle / non-draggable +- Static easing curves on M3E surfaces — `MotionScheme.expressive()` only +- SF Symbols / Material Symbols-Outlined-only (use variable axes) +- Inter / SF Pro on Android — Roboto Flex / Google Sans / Material default +- Centered FAB layouts where docked FAB pattern is canonical +- Standard Material 3 baseline 2023 — must be M3 Expressive +- Web-style desktop dashboards squeezed into mobile Compose +- Decorative motion that hides progress, state, or navigation changes + +## Step 7 — Reference apps that nail M3 Expressive + +- **Pixel Launcher / Android 16 System UI** — shape morph + springs +- **Google Calendar** — floating toolbar + tonal surfaces +- **Fitbit (2025 redesign)** — `ContainedLoadingIndicator` cycling shapes; floating toolbar +- **Pixel Camera 10.1** — wavy progress in capture +- **Google Docs/Sheets/Slides homepages** — M3E typography +- **Chrome (M3E redesign)** — adaptive nav +- **Read You** (community RSS, OSS) — canonical M3 + dynamic color +- **Androidify** sample app — official Compose M3E reference + +## Step 8 — Architecture defaults + +- **MVVM** with `ViewModel` + `StateFlow` + `collectAsStateWithLifecycle()` +- **Hilt** for DI +- **Navigation Compose 3** with type-safe routes +- **Coil 3** for image loading (replaces Glide for Compose-first apps) +- **Ktor** or **Retrofit + KotlinX Serialization** for networking +- **Room** for local persistence + +## Step 9 — Tokens & assets + +- M3 token spec: https://m3.material.io/foundations/design-tokens/how-to-use-tokens +- Theme Builder (web): https://m3.material.io/theme-builder +- Theme Builder Figma plugin: https://www.figma.com/community/plugin/1034969338659738588 +- M3 Figma kit: https://www.figma.com/community/file/1035203688168086460 +- Material Symbols: https://fonts.google.com/icons +- M3E component catalog: https://github.com/meticha/material-3-expressive-catalog + +Token JSON: see `../../assets/tokens/material3-expressive.json` diff --git a/plugins/f0d010c/stark/skills/apple-design/SKILL.md b/plugins/f0d010c/stark/skills/apple-design/SKILL.md new file mode 100644 index 000000000..3b6eb4f0e --- /dev/null +++ b/plugins/f0d010c/stark/skills/apple-design/SKILL.md @@ -0,0 +1,154 @@ +--- +name: apple-design +description: Build apps for iOS 26 / iPadOS 26 / macOS 26 (Tahoe) / watchOS 26 / visionOS 26 across all common stacks — system-like SwiftUI, branded SwiftUI (HIG + custom identity), React Native, Flutter Cupertino, and Electron/Tauri 2 for macOS. Use when the user asks for SwiftUI, an iOS app, iPad app, Mac app, Apple Watch app, visionOS app, an App Store deliverable, or anything Apple-platform deliverable. ALWAYS ask the user which track first — do not default to SwiftUI. SKIP when the target is only Android, Windows, or web-in-browser. +--- + +# apple-design — pick the track first + +Apple platforms have multiple stacks with different visual ceilings and cost. **Ask the user which one before any code.** + +## Step 0 (MANDATORY) — Ask the user which track + +> Which track for this app? +> +> **1. System-like native (SwiftUI strict + Liquid Glass + HIG)** — feels like Settings, Notes, Reminders, Mail. Best for: utilities, productivity. Visual ceiling: medium. Stays App Store-friendly. Examples: Things 3, NetNewsWire, Soulver. +> +> **2. Branded native (SwiftUI + HIG + custom identity)** — native chrome (Liquid Glass, SF Symbols, Dynamic Type) but bespoke content surface (custom typography, hero atmospheres, magazine layouts). Best for: consumer/media/creative apps that want fit-in *and* identity. Visual ceiling: high. Examples: Ivory, Reeder, Mela, Craft, CARROT Weather. +> +> **3. React Native (New Architecture + Fabric + Hermes)** — real UIKit views, decent native feel, JavaScript codebase, cross-platform with Android. Liquid Glass partial via `expo-glass-effect`. Best for: cross-platform apps with web-team velocity. Examples: Discord mobile, Coinbase, Microsoft Office mobile. +> +> **4. Flutter Cupertino** — Skia-painted UIKit-look. Always one OS behind, no Liquid Glass. Cross-platform. Best for: utility apps where pixel control beats native feel. Visual ceiling: high if you bring your own design language; low if you try to mimic iOS. +> +> **5. Electron / Tauri 2 (macOS only — no iOS)** — web stack desktop apps. Tauri 2 (~5MB, WKWebView) or Electron (~150MB, bundled Chromium). Same React/Tailwind/Motion code as web. Best for: cross-platform desktop with brand-first identity. Examples: Spotify, Discord, VSCode, Slack, Figma desktop, Linear. +> +> Which? Or describe priorities (App Store, brand vs HIG fit, cross-platform reach) and I'll pick. + +If brief gives a strong signal (e.g. "iOS App Store launch" → 1 or 2; "cross-platform with our existing React team" → 3 or 5; "web team building desktop-only" → 5), state your pick + reasoning in one sentence. If ambiguous, ask. + +## Step 0b — Once picked, route + +| Track | Reference docs | Default stack | +|---|---|---| +| 1. System-like SwiftUI | `../../references/apple-hig.md` + `../../references/liquid-glass.md` | SwiftUI 7 + Xcode 26 + iOS 26 SDK strict | +| 2. Branded SwiftUI | Same as 1 | Same as 1 + custom display font + hero atmospheres + bespoke surfaces | +| 3. React Native | `../../references/web-fonts.md` + cross-platform docs | RN 0.78+ New Arch + Expo Router + react-native-screens | +| 4. Flutter Cupertino | None for native fidelity (will feel imported) | Flutter 3+ stable | +| 5. Tauri 2 / Electron (macOS) | `../../references/web-fonts.md` + `../../references/web-motion.md` + `../../references/web-bans.md` + `../../references/awwwards-ceiling.md` | React 19 + Tailwind v4 + Motion | + +For tracks 3, 4, 5: web/cross-platform anti-slop rules apply. Read the web design references. + +State the chosen aesthetic direction and track in one sentence at top of response, then proceed. + +## Step 0c — UI decision brief + +Before code, read: + +- `../../references/ui-patterns/surface-taxonomy.md` +- `../../references/ui-patterns/ui-decision-brief.md` +- `../../references/ui-patterns/visual-hierarchy.md` +- `../../references/ui-patterns/motion-budget.md` + +Write the UI decision brief and adapt it to the chosen Apple platform. iPhone task flows need thumb reach and progressive disclosure; iPad/Mac productivity surfaces need NavigationSplitView, inspector, keyboard flow, and stable density; media/consumer apps may use branded surfaces while preserving HIG controls, SF typography, SF Symbols, Dynamic Type, and safe areas. + +## Step 1 — Liquid Glass first (only if track 1 or 2) + +Apple's unified design language across iOS 26, iPadOS 26, macOS 26 Tahoe, watchOS 26, tvOS 26, visionOS 26. Treat as default. + +Apply via: +- `.glassEffect()` modifier on surfaces that should refract underlying content +- `GlassEffectContainer { ... }` to coordinate multiple glass surfaces (avoids overlapping refraction artifacts) +- `.buttonStyle(.glass)` for buttons that should adopt Liquid Glass +- `.toolbar { ... }` automatically lifts to glass on iOS 26+ +- `.scrollEdgeEffectStyle(.soft)` — replaces hard chrome edges with material lensing + +Lineage to remember: Aqua → iOS 7 blur → Dynamic Island → visionOS → Liquid Glass. The aesthetic is "digital meta-material" — light bends through it. + +Read `../../references/liquid-glass.md` for full Liquid Glass adoption checklist. + +## Step 2 — SwiftUI 7 modern APIs (Swift 6.2 / Xcode 26) + +Always prefer: +- `@Observable` macro on view models — never `ObservableObject` + `@Published` +- `@Entry` for one-line `EnvironmentValues` / `FocusedValues` / `Transaction` keys +- `Group(subviews:)` and `ForEach(subviewsOf:)` for custom containers +- `MeshGradient(width:height:points:colors:)` for distinctive backgrounds — replaces flat gradients +- `NavigationSplitView` with `.inspector { ... }` for iPad/Mac three-pane +- `TabView` with sidebar-adaptable `.role` +- `.searchable` (morphs into a glass pill on iOS 26) +- `.symbolEffect(.bounce)` / `.pulse` / `.variableColor` / `.replace.byLayer` on SF Symbols +- `MotionScheme` and spring physics — `.spring(response:dampingFraction:)`, never linear/easeIn/easeOut on UI motion + +## Step 3 — HIG compliance + +- **Layout grid**: 8pt base, 4pt half-step. Never 10/15/20. Use `.padding()` defaults — they encode the system's grid. +- **Safe areas**: every screen wraps in safe area handling. `.safeAreaInset(edge:)` for content bars. +- **Dynamic Type**: support xSmall → AX5. Use `Font.TextStyle` (`.largeTitle`, `.title`, `.headline`, `.body`, `.caption`). Never hard-coded points. +- **SF Symbols 7** is the only icon system. ~6,900 glyphs, 9 weights × 3 scales. Use `Image(systemName:)`. +- **Accessibility**: `.accessibilityLabel/Hint/Value`, `.accessibilityElement(children:.combine)`, traits like `.isButton`, `.isHeader`. Mandatory. + +Read `../../references/apple-hig.md` for HIG section deep-dive. + +## Step 4 — macOS specifics (macOS 26 Tahoe) + +- SwiftUI is now first-class for new Mac apps. Drop into AppKit only for: complex `NSTextView` + custom rich text, Quick Look extensions, custom `NSToolbar` items, `NSOpenPanel` extensions. +- Catalyst is deprecated in spirit. Prefer SwiftUI multiplatform target. +- Patterns: + - `NavigationSplitView { sidebar } content: { ... } detail: { ... }` + - `.inspector { ... }` for trailing pane (Craft, Notes pattern) + - `MenuBarExtra("Name", systemImage: ...) { ... }` for menu-bar apps + - `Settings { TabView { ... } }` scene for prefs window +- Vibrancy materials: `.background(.regularMaterial)`, `.ultraThin/Thin/Regular/Thick/UltraThick` +- For sidebar background: `.background(NSVisualEffectView { $0.material = .sidebar })` via `NSViewRepresentable` if needed + +## Step 5 — Cross-platform fidelity warnings + +State the tradeoff if the user asks for non-Swift on Apple: + +| Stack | Liquid Glass adoption | Verdict | +|---|---|---| +| SwiftUI / UIKit native | Full automatic | **Use this** | +| React Native (New Arch + Fabric + Hermes) | Partial via expo-glass-effect / native modules | Decent for utility apps, off in nav transitions/haptics | +| Flutter Cupertino | Pixel-recreates iOS but always one OS behind, no Liquid Glass | Will feel wrong on iOS 26+ | +| .NET MAUI | Looks like Android in costume | Never use on Apple | + +If user insists on cross-platform, route to `cross-platform-design` and warn that any non-SwiftUI path will fail Liquid Glass adoption. + +## Step 6 — Anti-slop ban list (Apple-specific) + +- Inter / Roboto / SF Pro replaced by web fonts — only **SF Pro / SF Pro Rounded / SF Mono / New York** +- Material Design elevation shadows — use materials (`.regularMaterial`) and Liquid Glass instead +- Hamburger drawer navigation — use `TabView` (iOS), `NavigationSplitView` (iPad/Mac) +- FontAwesome / Material Symbols / Lucide icons — only SF Symbols 7 +- Linear/easeIn/easeOut animation curves — only spring physics +- `.padding(20)` magic numbers — use system spacing or 8/16/24 grid +- Bottom sheets without `.presentationDetents([.medium, .large])` +- Custom switch / checkbox UI replacing `Toggle` +- Full-bleed content under nav without `.scrollEdgeEffectStyle(.soft)` +- Ignoring `.safeAreaInset` — content collides with home indicator +- Hard-coded points instead of `Font.TextStyle` (breaks Dynamic Type) +- Custom scroll indicators — use `ScrollIndicators(.hidden)` only when justified +- Web-style dashboards squeezed into iPhone screens +- Decorative cards where grouped Form, List, inspector, or split view is the platform idiom + +## Step 7 — Reference apps that nail HIG + +- **Things 3** — typographic restraint, magic-plus, perfect Dynamic Type +- **Reeder Classic** / **Reeder 5** — `NavigationSplitView` exemplar on iPad/Mac +- **Ivory (Tapbots)** — bespoke yet HIG-correct; haptic + `.symbolEffect` choreography +- **Mela** — text-first, native share sheets, no chrome +- **Craft** — multi-pane Mac, inspector pattern, vibrancy +- **NetNewsWire** — open-source HIG textbook +- **Soulver 3** — Mac-native typography + sidebar +- **CARROT Weather** — system materials + variable color symbols +- **Overcast** — type hierarchy, Dynamic Type, accessibility +- **Fantastical** — sidebar + inspector + menu-bar mode + +## Step 8 — Tokens & assets + +- Apple Design Resources Figma kits (iOS 26, macOS 26): https://developer.apple.com/design/resources +- SF Symbols 7 app: https://developer.apple.com/sf-symbols +- HIG: https://developer.apple.com/design/human-interface-guidelines +- Icon Composer (WWDC25 session 361) for Liquid Glass app icons +- System color spec: https://developer.apple.com/design/human-interface-guidelines/color (use `.primary`, `.secondary`, `.tint`, `Color(.systemBackground)` — never raw hex) + +Token JSON: see `../../assets/tokens/apple-system.json` diff --git a/plugins/f0d010c/stark/skills/cross-platform-design/SKILL.md b/plugins/f0d010c/stark/skills/cross-platform-design/SKILL.md new file mode 100644 index 000000000..cf7d6af77 --- /dev/null +++ b/plugins/f0d010c/stark/skills/cross-platform-design/SKILL.md @@ -0,0 +1,122 @@ +--- +name: cross-platform-design +description: Use when the user wants one codebase across web, iOS, Android, Windows, and Mac, asks for the same app on all platforms, or names Compose Multiplatform, Tauri 2, React Native, Flutter, .NET MAUI, Avalonia, or Uno Platform. Builds cross-platform UI by translating each surface into the host platform's native idiom rather than pixel-cloning. SKIP when only one platform is targeted. +--- + +# cross-platform-design — translate idiom, not pixels + +Goal: ship one codebase that respects each platform's HIG/Material/Fluent — not a Flutter app that looks like Flutter on every OS. + +## Step 0 — Preserve UX and UI decisions + +If Stark produced a UX decision brief or UI decision brief, keep both as the source of truth. Translate them per platform instead of pixel-cloning. + +Read: + +- `../../references/ui-patterns/surface-taxonomy.md` +- `../../references/ui-patterns/ui-decision-brief.md` +- `../../references/ui-patterns/visual-hierarchy.md` +- `../../references/ui-patterns/motion-budget.md` + +The shared product should preserve job, state coverage, action hierarchy, and visual hierarchy. Navigation, controls, typography, icons, and motion must become platform-specific. + +## Step 1 — Pick the right framework for the design intent + +| User priority | Recommended stack | +|---|---| +| Native feel + Kotlin codebase + iOS support | **Compose Multiplatform 1.8+** (iOS stable since May 2025) | +| Tiny binary, web team, desktop-first | **Tauri 2** (Rust + native webviews; ~3MB) | +| Native Android views + iOS, large ecosystem | **React Native** (New Arch + Fabric + Hermes) | +| Single Skia raster across platforms (custom design system) | **Flutter** — only if pixel control matters more than native feel | +| .NET shop, XAML cross-platform | **Uno Platform 5+** (reuses WinUI XAML) | +| .NET shop, mobile-first | **.NET MAUI** (warn: weaker desktop, weaker iOS feel) | +| Cross-platform desktop + custom theming | **Avalonia 11** with Fluent/Mac themes | + +## Step 2 — Native-feel ranking by platform + +When the user picks a stack, **state the fidelity tradeoff per platform** in one line each. + +### Compose Multiplatform 1.8+ +- Android: native (excellent) +- iOS: stable but Material widgets won't feel HIG — you must implement Cupertino-styled Compose components, or accept a Material aesthetic on iOS +- Desktop: good for Compose-driven design, not native Fluent +- Web (Wasm): experimental + +### Tauri 2 +- Windows: WebView2 chrome — Mica works via window-backdrop API but font rendering and focus rings will look subtly off vs WinUI 3 +- macOS: WKWebView — looks like a web app, not an AppKit/SwiftUI app +- Linux: WebKitGTK +- Mobile (iOS/Android): preview, not production-ready + +### React Native (New Architecture) +- iOS: real UIKit views, decent. Liquid Glass requires `expo-glass-effect` or native modules; partial adoption. +- Android: real Android views, M3 themable but won't get spring physics or shape morphing without manual work. +- Desktop: react-native-windows / react-native-macos exist, fidelity weaker + +### Flutter +- All platforms: Skia custom-painted. Never feels native to anyone. +- Material 3 widgets exist but lag platform updates (no spring physics parity, no shape morphing primitives, no real dynamic color). +- **Avoid** for any project where "native feel" is a stated requirement. + +### Uno Platform +- Windows: native WinUI (excellent) +- iOS / Android / Mac / Web: reuses XAML rendering — distinctive fidelity but not 1:1 with each platform's idiom +- Best XAML cross-platform path + +### .NET MAUI +- Windows: weak WinUI integration +- macOS: Catalyst (deprecated direction) +- iOS: looks like Android in costume +- **Generally avoid for design-first work** + +## Step 3 — Translation rules: same product, different idiom + +**Settings screen example:** +- iOS → grouped `Form` with `Section { ... }` headers, Liquid Glass toolbar, switch toggles +- Android → `LargeTopAppBar` + `LazyColumn` with `ListItem` rows, switches with M3 thumbs +- Windows → `NavigationView` + scrollable `SettingsCard` stack with Mica backdrop +- Web → asymmetric grid with sidebar nav and editorial section headers + +**Tab bar example:** +- iOS → bottom `TabView` (5 tabs max, Liquid Glass) +- Android → `NavigationBar` (3–5) or `NavigationRail` adaptive +- Windows → `NavigationView` Top or Left +- Web → top nav with motion-reveal + +**List detail example:** +- iOS → `NavigationSplitView` on iPad/Mac, push-pop on iPhone +- Android → `ListDetailPaneScaffold` (adaptive) +- Windows → Master-detail with Mica +- Web → URL-driven two-pane with View Transitions + +Never copy the iOS tab bar onto Windows. Never copy the Android FAB onto iOS. Idiom > pixel. + +## Step 4 — When to route to a single-platform skill + +If the user is shipping to one canonical platform first (almost always the case), route to that platform's skill (`apple-design`, `android-design`, `windows-design`, `web-design`) and translate later. Don't start in cross-platform mode unless they explicitly say "build cross-platform from day one." + +## Step 5 — Anti-slop ban list (cross-platform-specific) + +- Same UI pixel-for-pixel on every platform +- Defaulting to Flutter without warning about non-native feel +- Defaulting to Electron (use Tauri 2 if web stack is mandated) +- Material widgets unmodified on iOS — must Cupertino-skin or accept "Material on iOS" warning +- Cupertino widgets unmodified on Android — same in reverse +- Ignoring per-platform navigation idioms (always-bottom-tabs, always-hamburger) +- One typeface across all platforms — each OS has a system face +- One motion language across all platforms when native motion differs +- One density level across mobile, tablet, desktop, and web + +## Step 6 — Reference cross-platform apps that translate well + +- **Notion** — web-first but adapts respectably to each native platform +- **Telegram** — fully native on each platform; same product, different code per OS +- **Spotify** — same brand, idiomatic per platform +- **Linear** — desktop via Electron but obsessively polished; web is canonical + +## Step 7 — Tokens & assets + +When generating cross-platform output, ship tokens once and translate: +- Use the **DTCG W3C token format** as the source of truth +- See `../../scripts/token_export.py` to translate one token JSON into Tailwind theme + Compose Material3 ColorScheme + SwiftUI Color extension + Fluent ResourceDictionary +- See `../../assets/tokens/` for per-platform reference token bundles diff --git a/plugins/f0d010c/stark/skills/design-router/SKILL.md b/plugins/f0d010c/stark/skills/design-router/SKILL.md new file mode 100644 index 000000000..4c4457de9 --- /dev/null +++ b/plugins/f0d010c/stark/skills/design-router/SKILL.md @@ -0,0 +1,70 @@ +--- +name: design-router +description: 'Use when the user asks to build, design, mock up, scaffold, audit, or improve any interface, flow, screen, page, component, app, UX, onboarding, checkout, dashboard workflow, or product flow and the target platform or flow is ambiguous. Routes to ux-design, web, Windows, Apple, Android, cross-platform, or design-token skills. SKIP when the request explicitly names one platform and no UX flow work is implied.' +--- + +# design-router — platform dispatch + +This skill is the entry point when a UI/UX request is ambiguous. Goal: pick the right UX and platform skill, do not over-eagerly route to web. + +## Step 0 - Decide whether UX comes first + +Route to `ux-design` before platform visuals when the request includes: + +- "UX", "user journey", "flow", "wireframe", "information architecture", "IA", "usability" +- onboarding, signup, checkout, paywall, forms, settings, permissions, dashboard workflow, admin workflow +- CRM, admin panel, internal tool, SaaS dashboard, marketplace, editor/canvas tool, setup wizard, command palette, data table +- empty/loading/error states, long-running task progress, retry/resume, bulk actions, saved filters, audit trails +- making an app easier to use, less confusing, better for daily use, or better for conversion/retention + +If the request is both UX and platform-specific, read `ux-design` first, then the matching platform skill. + +## Step 1 — Read the request for platform signals + +Scan for explicit signals (in priority order): + +| Signal in request | Route to | +|---|---| +| "onboarding", "checkout", "signup", "form flow", "empty state", "loading state", "error state", "admin workflow", "CRM", "internal tool", "SaaS dashboard", "user journey" | `ux-design` first, then platform skill | +| "translate this UI", "translate this screen", "translate this design", "port this UI", "convert this screen", "from iOS to Windows", "from Apple to Android" | `cross-platform-design` first, then the target platform skill | +| "design tokens", "export tokens", "DTCG", "token JSON", "ColorScheme", "Typography tokens", "Tailwind tokens", "SwiftUI tokens", "Compose tokens" | `design-tokens` | +| `.tsx` `.jsx` `.html` `.svelte` `.vue`, "Tailwind", "Next.js", "Astro", "shadcn", "landing page", "marketing site", "dashboard in React" | `web-design` | +| `.xaml` `.cs` (with `WinUI`/`UWP`/`WPF`), "Windows app", "Fluent", "Mica", "WinUI", "Win11", "Microsoft Store app", "PowerToys-style" | `windows-design` | +| `.swift` `.swiftui`, "SwiftUI", "iOS app", "iPadOS", "macOS", "Liquid Glass", "HIG", "SF Symbols", "App Store", "Tahoe" | `apple-design` | +| `.kt` `.kts`, "Compose", "Jetpack Compose", "Material 3", "Material You", "Pixel app", "Android app" | `android-design` | +| "Tauri", "Electron", "Flutter", "React Native", "Expo", "Compose Multiplatform", "CMP", "Uno Platform", "Avalonia", "MAUI" | `cross-platform-design` | + +## Step 2 — When signals are absent + +Ask one question, no more: + +> "Which platform is this for? **(1) Web** - React/Tailwind/Astro **(2) Windows** - WinUI 3 / WPF **(3) iOS / macOS** - SwiftUI **(4) Android** - Jetpack Compose **(5) Cross-platform** - Tauri 2, Compose Multiplatform, React Native, Flutter. If this is mainly UX, describe the user flow and I'll start there." + +Do not assume web. Web defaults are how the official `frontend-design` skill produces native-looking-wrong code. + +## Step 3 — Multi-target requests + +If the user wants the same product on multiple platforms (e.g. "iOS + Android + web"): +1. Ask which platform is **canonical** (where the design originates). Usually iOS or web. +2. Build the canonical version first. +3. Then translate per-platform via `cross-platform-design` or successive single-platform skills, **respecting each idiom**, not pixel-cloning. + +Same product ≠ same UI. A Settings screen on iOS uses grouped Form, on Android uses LargeTopAppBar + LazyColumn, on Windows uses NavigationView + SettingsCard. Translate idiom, not pixels. + +## Step 4 — Hand off + +Once routed, the UX or platform SKILL.md takes over. State what you picked and why in one sentence, then proceed. + +If UX ran first, carry its `UX decision brief` into the platform skill and preserve the job, state coverage, action hierarchy, and recovery path. + +For any build/redesign request, also carry a `UI decision brief` from `../../references/ui-patterns/ui-decision-brief.md` into the platform skill. This keeps visual hierarchy, density, component grammar, and motion budget explicit. + +## Anti-patterns this skill exists to prevent + +- Generating React/Tailwind when user wants a Windows app +- Pasting Inter on iOS where SF Pro belongs +- Reaching for Tauri/Electron when the user said "Windows app" (those are web-in-window — use WinUI 3 unless web stack is mandated) +- Defaulting to Material Design on Apple platforms +- Making a beautiful screen while ignoring empty/error/loading states and repeated-use flow + +When uncertain, ask. One clarifying question is cheaper than 800 lines of wrong-platform code. diff --git a/plugins/f0d010c/stark/skills/design-tokens/SKILL.md b/plugins/f0d010c/stark/skills/design-tokens/SKILL.md new file mode 100644 index 000000000..023a93cdf --- /dev/null +++ b/plugins/f0d010c/stark/skills/design-tokens/SKILL.md @@ -0,0 +1,87 @@ +--- +name: design-tokens +description: Use when the user asks for design tokens, translate these tokens, export tokens, make a Compose color scheme from a Figma palette, audit tokens, or share a single token source across web and native. Generates, audits, and translates W3C DTCG tokens to Tailwind v4 @theme, Compose Material3 ColorScheme and Typography, SwiftUI Color/Font extensions, and WinUI ResourceDictionary. SKIP when no token work is involved. +--- + +# design-tokens — single source, every platform + +Goal: one DTCG-format JSON, four platform outputs. No drift. + +## Step 1 — Source format: W3C DTCG + +Every token bundle this skill produces or consumes is in W3C Design Tokens Community Group format. Keys: +- `$value` — the literal value +- `$type` — `color | dimension | fontFamily | fontWeight | duration | shadow | typography` +- `$description` — human-readable rationale (kept in the token; not a comment) + +Example: + +```json +{ + "color": { + "brand": { + "primary": { "$value": "#3b1c0f", "$type": "color", "$description": "Hero accent — used like a weapon" }, + "primary-hover": { "$value": "{color.brand.primary}", "$type": "color" } + } + }, + "spacing": { + "xs": { "$value": "4px", "$type": "dimension" }, + "sm": { "$value": "8px", "$type": "dimension" } + }, + "type": { + "display": { + "$value": { "fontFamily": "PP Editorial New", "fontSize": "72px", "fontWeight": 400, "lineHeight": 1.05 }, + "$type": "typography" + } + } +} +``` + +## Step 2 — Platform translation matrix + +| Platform | Output target | +|---|---| +| Web (Tailwind v4) | `@theme { --color-brand-primary: ...; }` block | +| Web (CSS) | `:root { --color-brand-primary: ...; }` | +| Apple (SwiftUI) | `extension Color { static let brandPrimary = ... }` + `Color` asset catalog JSON | +| Android (Compose) | `ColorScheme(primary = Color(0xFF...), ...)` + `Typography` | +| Windows (WinUI 3) | `` with ``, ``, `` | + +Use `../../scripts/token_export.py` for the translation — never hand-translate. Tokens drift fast. + +## Step 3 — When you should NOT generate tokens + +Three cases where token work is wrong: +1. The user wants ONE platform — let that platform skill use its native idiom directly. Tokens are for reuse. +2. The brief is "Awwwards-tier landing page" — tokens flatten the bespoke choices that make it distinctive. +3. The team has no system to maintain. Tokens without governance become stale faster than they help. + +State this explicitly if the user asks to "tokenize everything." Push back once. + +## Step 4 — Auditing existing tokens + +When asked to audit a token set: + +1. **Coverage check** — does it cover the 5 layers? color (semantic + raw), spacing, typography, motion, elevation/material. +2. **Semantic vs raw discipline** — are there "primary-button-bg" tokens (semantic) AND "blue-500" tokens (raw)? Both layers, no shortcuts. +3. **Reference resolution** — semantic tokens must reference raw, never the inverse. +4. **Dark mode parity** — every semantic color has a dark variant. +5. **Platform-specific bans** — flag any token that won't survive translation (e.g. CSS `box-shadow` for native, where elevation is tonal). + +## Step 5 — Anti-slop ban list (token-specific) + +- Hex colors with no semantic name (`#3b82f6` exposed as a token name) +- 100+ raw colors with no semantic layer +- Spacing scales that aren't 4-based on Windows/Android, 8-based on Apple, fluid on web +- One token bundle declared "the source of truth" but only generated for web (the most common failure) +- Tailwind classes baked into tokens (defeats translation) +- Skipping `$type` (some tools won't validate without it) + +## Step 6 — Reference token bundles + +Shipped in `../../assets/tokens/`: +- `fluent-2.json` — Microsoft Fluent 2 reference +- `material3-expressive.json` — M3E reference (M3E adds wave/morph tokens vs M3) +- `apple-system.json` — iOS/macOS semantic system colors +- `awwwards-editorial.json` — bespoke "editorial Swiss" example +- `awwwards-brutalist.json` — bespoke "tactile brutalist" example diff --git a/plugins/f0d010c/stark/skills/ux-design/SKILL.md b/plugins/f0d010c/stark/skills/ux-design/SKILL.md new file mode 100644 index 000000000..3628aa072 --- /dev/null +++ b/plugins/f0d010c/stark/skills/ux-design/SKILL.md @@ -0,0 +1,174 @@ +--- +name: ux-design +description: Use when the user asks for UX, product flow, user journey, wireframes, usability, conversion, onboarding, checkout, signup, navigation, forms, state design, dashboard workflows, or making an app easier to use over time. Designs and audits user experience flows, information architecture, forms, onboarding, dashboards, settings, empty/loading/error states, activation, retention, and repeated-use product ergonomics before visual polish. Pair with platform UI skills after the UX flow is clear. +--- + +# ux-design - product flow before pixels + +Use this skill when the product has to be understandable and usable, not just attractive. The output should make the user path clearer, reduce unnecessary decisions, and define states that survive real use. + +## Step 1 - Identify the job and user mode + +Before designing screens, state the smallest useful context: + +- Primary job: what the user is trying to finish. +- User mode: first-time, returning, power user, admin, buyer, creator, operator, or support. +- Frequency: one-time, occasional, daily, or high-volume repeated use. +- Risk: low-risk browse, reversible edit, money/data/security impact, or destructive action. + +If any of these are unclear and materially affect the flow, ask one short question. If the answer is easy to infer from the request, infer it and continue. + +Do not interrogate the user with a product-strategy questionnaire before helping. The skill should make useful assumptions, name them briefly, and move. + +## Step 2 - Map the flow + +Write the minimum useful path: + +1. Entry point +2. First meaningful action +3. Required decision +4. Feedback after action +5. Success state +6. Recovery path when something fails + +Prefer fewer screens when the user is trying to finish one job. Prefer separate steps when the user is making risky, costly, or hard-to-reverse decisions. + +## Step 2.5 - Produce the UX decision brief + +Before visual design or code, write a compact brief. Keep it short enough to pass into another skill: + +```md +UX decision brief +- Job: ... +- User mode: ... +- Frequency/risk: ... +- Pattern: ... +- Primary action: ... +- Secondary actions: ... +- Core path: entry -> action -> feedback -> success +- Recovery path: ... +- Required states: empty, loading, partial, error, permission, success, long-running +- Handoff constraints: ... +``` + +This brief is the contract. The platform skill may change visual treatment, but it must not erase the chosen job, action hierarchy, state coverage, or recovery path. + +## Step 3 - Design the states + +Every production UI needs these states: + +- Empty: what the user sees before data exists. +- Loading: what changes while the system is working. +- Partial: some data exists, some is missing. +- Error: what failed, why it matters, and the next action. +- Permission: what is blocked and how to request access. +- Success: what happened and what the user can do next. +- Long-running: progress, cancellation, retry, and resume behavior. + +Do not ship only the happy path. + +For public demos and generated proof projects, include at least one non-happy state in the visible UI: an empty state, blocked permission, failed sync, queued job, retry panel, stale data banner, or partial result. This makes the output feel like a real product instead of a polished poster. + +## Step 4 - Reduce cognitive load + +Apply these rules: + +- Put the next action where the user's eye already is. +- Use one primary action per surface. +- Group by task, not by database object. +- Prefer progressive disclosure over dense first screens. +- Keep labels concrete: "Invite teammate", not "Manage". +- Make defaults safe and visible. +- Keep destructive actions separated, confirmed, and undoable when possible. +- Make repeated actions faster than first-time actions. + +For high-frequency tools, optimize scan speed, keyboard flow, saved filters, bulk actions, and stable layout. For consumer onboarding, optimize motivation, trust, and the shortest path to first value. + +## Step 4.5 - Match the product type + +Use the product type to decide what "good UX" means: + +| Product type | Optimize for | Avoid | +|---|---|---| +| SaaS dashboard | fast scanning, saved filters, drilldowns, clear priority, visible operational thesis | marketing-page spacing, decorative cards, hidden filters, generic CRM furniture | +| CRM/admin/internal tool | repeat speed, bulk actions, auditability, permissions, domain-specific task language | oversized empty space, playful copy, modal chains, interchangeable labels | +| Creative/editor tool | canvas focus, tool discoverability, undo/redo, stable panels | layout shifts, buried controls, destructive defaults | +| Marketplace/ecommerce | trust, comparison, price/shipping clarity, recovery | surprise costs, forced account creation, vague stock states | +| Onboarding/setup | first value, motivation, resumability, skip paths | long forms before value, fake progress, no return path | +| AI agent/tool run | plan preview, progress, artifacts, retry, stop/resume | invisible work, ambiguous completion, no trace of outputs | + +If the request sounds like a real product people will use repeatedly, bias toward operational density and predictable navigation. If it is a one-off marketing page, bias toward clarity, brand memory, and conversion path. + +## Step 4.6 - Load a contextual pattern brief + +If the product type clearly matches one of these contexts, read the matching brief before choosing the final UX pattern: + +| Context | Read | +|---|---| +| Agent/tool run, background automation, long-running export/import | `../../references/ux-patterns/ai-agent-run.md` | +| SaaS dashboard, CRM, admin panel, internal tool, support queue | `../../references/ux-patterns/operational-dashboard.md` | +| First-run setup, trial activation, import/setup flow | `../../references/ux-patterns/activation-onboarding.md` | +| Checkout, paywall, pricing, upgrade, plan comparison | `../../references/ux-patterns/checkout-upgrade.md` | +| Editor, builder, canvas, creative tool, IDE-like surface | `../../references/ux-patterns/editor-canvas.md` | + +Use a brief only when the context fits. If no brief fits, proceed from the product type table and the user's actual constraints. + +The brief should influence the UX decision brief, especially: + +- Pattern +- Primary and secondary actions +- Required states +- Recovery path +- Handoff constraints + +Do not copy a referenced app or blindly apply a pattern because it is common. A shipped screen is evidence that a real product team used a decision, not proof that it is best for every product. + +## Step 5 - Choose the UX pattern + +Pick one pattern and name it before visual design: + +| Need | Pattern | +|---|---| +| First run | Guided setup with skip/resume | +| Complex creation | Wizard with review step | +| Frequent operations | Command surface + saved views | +| Data-heavy work | Master/detail + filters + bulk actions | +| Monitoring | Dashboard with priority stack and drilldown | +| Settings | Searchable grouped settings + inline validation | +| Checkout/signup | Short form + transparent cost/risk + recovery | +| Collaboration | Activity timeline + comments + ownership | +| AI/tool execution | Plan preview + progress + artifacts + retry | +| Public demo/proof project | Product-specific job + proof surface + one non-happy state | + +If two patterns fit, pick the one that reduces the riskiest failure mode. For example, choose a wizard over a single dense form when errors are costly, but choose command surface + saved views for repeated internal operations. + +## Step 6 - Hand off to UI + +After the UX shape is clear, route to the platform skill: + +- Web visuals: `../web-design/SKILL.md` +- Windows visuals: `../windows-design/SKILL.md` +- Apple visuals: `../apple-design/SKILL.md` +- Android visuals: `../android-design/SKILL.md` +- Cross-platform translation: `../cross-platform-design/SKILL.md` + +Pass the UX decisions into that skill as constraints. Do not let visual direction erase task flow, state coverage, or platform idioms. + +When a contextual pattern brief was used, include its name in the handoff constraints so the platform skill knows which product behavior must survive visual design. + +## UX audit checklist + +Before final delivery, check: + +1. Is the primary job obvious in the first screen? +2. Can a new user reach first value without reading documentation? +3. Can a returning user repeat the core task faster? +4. Are empty, loading, error, permission, and success states defined? +5. Is there one clear primary action per surface? +6. Are risky actions confirmed, separated, or undoable? +7. Do form errors appear near the fields they describe? +8. Does the layout support scanning, not just looking good in a screenshot? +9. Does navigation match the user's mental model? +10. Is the next step clear after every action? + +If any answer is no, fix the flow before polishing visuals. diff --git a/plugins/f0d010c/stark/skills/web-design/SKILL.md b/plugins/f0d010c/stark/skills/web-design/SKILL.md new file mode 100644 index 000000000..7ca49b2de --- /dev/null +++ b/plugins/f0d010c/stark/skills/web-design/SKILL.md @@ -0,0 +1,255 @@ +--- +name: web-design +description: Use for web apps, landing pages, dashboards, React/Next/Vite/Tailwind frontends, web UI reference planning, animation, motion, scrolling, GSAP, Motion, Lenis, command palettes, split panes, and frontend interaction decisions. Builds web surfaces with the right surface type, visual direction, hierarchy, motion, layout, copy, assets, and anti-slop discipline. ALWAYS choose surface type and ask which aesthetic direction first. SKIP when the target is a native desktop/mobile app. +--- + +# web-design — pick the direction first, then execute precisely + +Goal: build web surfaces that feel specific, useful, and visually deliberate. Marketing pages can chase an Awwwards-level ceiling; dashboards, editors, docs, checkout, and agent-run UIs should prioritize product proof, scan speed, state coverage, and stable interaction before spectacle. + +## Step 0 (MANDATORY) — Choose surface type, then direction + +Before aesthetic direction, classify the surface using `../../references/ui-patterns/surface-taxonomy.md`: + +- Marketing page +- Cinematic campaign page +- Editorial scroll story +- Product proof landing page +- Immersive brand page +- SaaS dashboard +- Editor/canvas +- Checkout/upgrade +- Agent/tool run +- Mobile task flow + +Then write the `UI decision brief` from `../../references/ui-patterns/ui-decision-brief.md`. For dashboards, editors, checkouts, and agent-run UIs, preserve the UX decision brief if one exists and bias toward usable density over Awwwards spectacle. + +For polished, original, memorable, high-craft, campaign, or "best-looking" requests, read `../../references/ui-patterns/creative-direction.md` before visual styling. Define a creative direction brief with world, metaphor, material language, typography personality, layout grammar, repeated motif, forbidden defaults, one tasteful risk, and restraints. + +For cinematic campaign, editorial scroll story, product proof, or immersive brand pages, read `../../references/ui-patterns/cinematic-landing-system.md` before choosing motion. Define key art, art direction, typography discipline, section rhythm, and page choreography first. Motion should reveal the system, not compensate for weak composition. + +Do not force an expressive landing-page composition onto a repeated-use web app. For operational surfaces, read `../../references/ui-patterns/product-quality-bar.md`, `../../references/ui-patterns/visual-hierarchy.md`, `../../references/ui-patterns/responsive-containment.md`, `../../references/ui-patterns/motion-budget.md`, `../../references/ui-patterns/interaction-techniques.md`, and `../../references/ui-patterns/ui-audit-rubric.md` before coding. + +When the site needs imagery, proof visuals, icons, screenshots, typography, or references, also read `../../references/ui-patterns/asset-selection.md` and include an asset plan before code. If the user is using GPT/Codex and image generation is available, generated bitmap assets are allowed for fictional product visuals, editorial hero imagery, textures, and empty states when they support the product job. + +When using shipped products, Mobbin/Figma screens, docs, or screenshots as references, read `../../references/ui-patterns/reference-analysis.md` and produce a reference extraction brief. Borrow structure, interaction, state, and responsive decisions; never copy visual identity. + +When using high-craft landing pages as references, extract first-viewport composition, key-art framing, type scale, section sequence, asset reuse, and motion pacing. Do not copy the subject, exact layout, assets, copy, or trade dress. + +## Step 0a (MANDATORY) — Ask the user which direction + +Six distinct aesthetic directions exist. Each has its own typography, palette, motion language, copy voice, layout grammar, reference apps, ban list. **Pick before any code.** Never blend directions — that produces the AI-slop middle. + +> Which direction for this site? +> +> **1. Editorial Swiss revival** — generous whitespace, asymmetric grid, neo-serif headlines, monospace metadata, italic emphasis, single accent. Refs: rauchg.com, are.na, robinrendle.com, Hayes & Co (our example). Reading-room vibe, considered restraint. +> +> **2. Tactile brutalism** — visible grids, harsh type, color clashes, raw seams, mono-driven, pure-black or hi-vis accents. Refs: werkstatt.fyi, fram.io, off-brand.work. "Human-made" reaction signal. +> +> **3. Type-as-hero** — oversized variable display fonts, scroll-morphing letterforms, no decorative imagery, type *is* the design. Refs: igloo.inc (Awwwards SOTY 2025), lehman.berlin, Lando Norris site. Maximalist typography flex. +> +> **4. Glow + grain** — multicolor glowing backdrops with tactile grain, atmospheric mesh gradients, dark-mode editorial. Refs: stripe.com/sessions, openai.com, vercel.com hero, liveblocks.io. Atmosphere-driven. +> +> **5. Industrial monospace** — Söhne Mono / JetBrains Mono everywhere, terminal references, log-driven hero, technical aesthetic, no decoration. Refs: railway.com, fly.io, raycast.com, resend.com. Dev-tool benchmark. +> +> **6. Active bento** — interactive bento tiles, expanding/morphing cards, autoplay video on hover, layered reveal. Not the static 2023 bento. Refs: linear.app/method, vercel.com/templates, arc.net. Product-led. +> +> Which? Or describe vibe (luxury vs raw vs technical vs maximalist) and I'll pick. + +If the brief gives strong signal (e.g. "watch maker / luxury minimal" → 1; "AI dev tool, terminal vibe" → 5; "Awwwards SOTY ambition with massive type" → 3), state your pick + reasoning in one sentence. If ambiguous, ask. + +Once picked, **load the matching direction reference** from `../../references/web-direction-{name}.md`. Each contains: typography scale, palette, layout grid, motion moves, copy voice, reference apps, direction-specific ban list. + +For operational dashboards, admin tools, and editors, ask direction in a restrained way: "systematic / editorial / industrial / branded product-led" is enough. Do not ask for Awwwards direction if it would harm repeated use. + +## Step 0b — Stack questions (after surface and direction picked) + +Before choosing a framework, read `../../references/ui-patterns/web-implementation-tracks.md` and produce the implementation track brief. React is a first-class option for advanced interactive work, but it is not the automatic default. + +Ask in one batch: +- **Framework**: static HTML/CSS/JS, Vite + React, Next, Astro, SvelteKit, Solid, Qwik, or existing project stack? +- **CSS**: Tailwind v4 default. Vanilla CSS w/ `@scope`/`@layer` if user prefers no utility classes. +- **Motion library**: choose from `../../references/ui-patterns/interaction-techniques.md`. CSS first for simple transitions, Motion for React product motion, GSAP only for timeline/pinned storytelling, Lenis only for brand scroll feel. +- **Smooth scroll**: default off. Only add if direction and surface type justify it; never add to dashboards, docs, forms, checkout, editors, or admin tools. + +State stack pick at top of response in one sentence. + +## Step 1 — Technique inventory (use as palette, deploy 2-4 per project) + +The model has access to all of these. **Don't deploy all of them on every site** — over-motion is its own tell. Awwwards SOTY sites typically have 2-4 signature motion moments + restrained baseline. + +Read `../../references/web-patterns/README.md` first to choose the right pattern family, then read the specific `../../references/web-patterns/*.md` files you will use. List below: + +### Motion / Interaction +- **Letter-stagger reveal** — hero text drops in word-by-word w/ spring physics +- **Variable-font axis hover** — `font-variation-settings` shifts on hover/scroll (weight, optical size, grade) +- **Page-load curtain** — paper-colored mask slides off, contents reveal beneath +- **Custom cursor** — branded dot + label morph ("VIEW", "READ", "PLAY") on hoverable elements +- **Magnetic CTAs** — buttons attract cursor within radius +- **Scroll-pinned section** — pin viewport, content advances frame-by-frame as scroll progresses +- **Scroll-driven CSS** — `animation-timeline: view()` / `scroll()` for native scroll-tied animation +- **View Transitions API** — `document.startViewTransition()` for SPA route changes + shared element transitions +- **Layered parallax** — multiple z-layers scroll at different speeds for depth +- **3D tilt card** — perspective + rotateX/Y on cursor position +- **Marquee band** — horizontal scrolling text band +- **Connected animation** — `layoutId` (Motion) for hero element morph between pages +- **Mesh gradient** — multi-stop SVG/CSS radial gradients, animated +- **Lenis smooth scroll** — eased momentum scroll +- **GSAP ScrollTrigger** — for complex timeline-driven effects +- **Scroll-snapping** — section-by-section CSS scroll-snap +- **Symbol cycling** — text that cycles through related symbols/glyphs on hover + +### Typography techniques +- **Variable font axis play** — wght / opsz / grade hover transitions +- **Italic emphasis within headline** — `word` for selective italic +- **Monospace caps eyebrow** — `font-mono text-[10px] tracking-[0.32em] uppercase` +- **§ section markers** — Manifesto-style `§ 01` `§ 02` numbering +- **Scroll-tied letter spacing** — `letter-spacing` shifts as scroll advances +- **Type-as-image** — text as primary visual, no decorative imagery +- **Mixed scripts** — Latin display + Greek/Cyrillic/CJK accents for international voice +- **Drop caps** — first letter of paragraph sized 4-6× body +- **Hanging punctuation** — `hanging-punctuation: first` for editorial polish + +### Layout +- **Asymmetric grid** — content offset from center, alternating sides +- **Sticky § markers** — left rail with `sticky` `§ 01` numerals +- **Magazine spread** — multi-column body, generous line-height +- **Hero + rail** — hero takes 7-8 cols, supporting nav/meta in 2-3 col rail +- **Pinned scroll-tied** — sticky + scroll-driven content swap +- **Asymmetric featured grid** — hero tile + smaller tiles, varying sizes +- **Magazine masthead title bar** — wordmark + accent + tagline in mono caps + +### Color +- **Single hero accent** — one signature color, used like a weapon +- **Warm off-white** — never pure `#fff` (try `#FAF8F3`, `#F1ECE2`, `#FBF6EB`) +- **Warm-tinted near-black** — never pure `#000` (try `oklch(0.18 0.02 280)`) +- **Mesh gradient atmospheres** — multi-stop radial gradients layered +- **Mix-blend-mode** — `mix-blend-mode: difference` / `multiply` for dramatic interaction + +### Asset generation +- **CSS-rendered illustration** — gradients + shapes for hero visuals +- **SVG illustration** — geometric, abstract, layered (see `../../references/web-svg-illustration.md`) +- **Generated bitmap image** — use GPT/Codex image generation when available for specific hero imagery, product concept art, textures, realistic scenes, or empty-state illustrations +- **Generated text glyphs** — large characters as image substitute +- **Mesh gradient as hero** — full-bleed atmospheric backdrop +- Read `../../references/web-svg-illustration.md` for full asset-generation strategies + +## Step 2 — Always do these (non-negotiable baseline) + +Every web output, regardless of direction: + +- **Real custom typography** — never Inter / Space Groteske / Roboto / system-ui as primary face. Pick from `../../references/web-fonts.md`. +- **Real semantic copy** — no "Lorem ipsum", no "Built for modern teams", no "10x faster". Read `../../references/web-copy-voice.md`. +- **Real visual content** — generate SVG / CSS art, never `` or `via.placeholder.com`. +- **Asset plan** — decide icons, screenshots, references, generated images, typography, and attribution before adding assets. +- **Reference extraction** — if using real product references, extract job, IA, hierarchy, state coverage, interaction, recovery, responsive behavior, and asset use; do not copy visuals. +- **Accessibility baseline** — semantic HTML, focus-visible rings, WCAG AA contrast, `prefers-reduced-motion` respected. +- **Performance discipline** — lazy-load below-fold, no layout thrashing in scroll motion, font-display: swap. +- **Surface-fit baseline** — marketing pages may be spacious and expressive; dashboards, editors, checkouts, and agent-run UIs must preserve task density, stable controls, and state visibility. +- **Responsive containment** — nav rows, dense tables, toolbars, inspectors, and long labels must wrap, collapse, or scroll inside their own region; never leave mobile/tablet page-level horizontal overflow. +- **Quality bar note** — for public-facing or "make it better" work, state the specific job, proof surface, required states, scan-speed decision, and memorable anchor before implementation. +- **Creative direction** — for original/high-craft work, state the world, metaphor, material language, repeated motif, forbidden defaults, tasteful risk, and restraints. +- **Implementation track** — choose static, Vite React, Next, Astro, or existing stack by actual interaction needs and dependency risk. +- **Interaction decision** — when motion/scrolling is non-trivial, state budget, techniques, library choice, why it fits, reduced-motion behavior, and rejected techniques. +- **Cinematic system** — for campaign-style pages, state the mode, key art, art direction, typography system, page rhythm, and repeated motif before implementation. + +## Step 3 — Deploy 2-4 signature motion moments + +Pick from technique inventory above. Examples per direction: + +- **Editorial**: letter-stagger hero + scroll-driven `reveal-on-scroll` + variable-font hover + Lenis smooth scroll +- **Brutalist**: instant page render (no curtain) + cursor-following snap + marquee + `mix-blend-mode: difference` highlight +- **Type-as-hero**: scroll-pinned headline morph + variable-axis cursor-Y hover + page-load curtain + mesh gradient atmosphere +- **Glow + grain**: page-load curtain + mesh atmosphere + scroll-driven glow shift + magnetic CTAs +- **Industrial mono**: terminal-style typewriter intro + log-stream marquee + monospace number tickers + cursor swap +- **Active bento**: layoutId connected animations + tile-expand on hover + scroll-snap sections + custom cursor "VIEW" +- **Cinematic campaign**: giant composed title + key-art parallax + one pinned craft/proof moment + collection/gallery transition + +Don't deploy all 17 techniques. Pick 2-4 that reinforce the direction. + +Before adding GSAP, Lenis, native scroll-driven CSS, custom cursors, pinned scroll, parallax, or view transitions, check `../../references/ui-patterns/interaction-techniques.md`. If the surface is a dashboard, docs, checkout, editor, admin panel, or form-heavy workflow, default back to subtle/functional interaction. + +## Step 4 — Anti-slop ban list (always enforced) + +Read `../../references/web-bans.md` for full list. Top tells of AI-generated UI: + +- `from-purple-500 to-pink-500` gradients (top tell) +- Inter / Space Grotesk as primary face +- Three feature cards w/ Lucide icons + "Built for modern teams" +- Hero: H1 + sub + indigo button + ghost button (universal SaaS) +- `rounded-2xl` everywhere uniformly +- Default shadcn theme untouched +- `bg-slate-950` + `text-slate-300` + indigo accent (VS-Code-as-product) +- Centered everything, no asymmetry +- `` / via.placeholder.com / unsplash random +- Lorem ipsum copy +- Identical 80px section padding throughout (kills rhythm) +- "Powered by AI" sparkle badges +- Emoji bullets + +## Step 5 — Forbidden combinations (anti-patterns) + +Within direction-aware design, certain combos are wrong: +- **Editorial Swiss + Material shadows** → use rules + warm paper, never elevation +- **Brutalist + soft springs** → snappy timing only (`cubic-bezier(0.85,0,0.15,1)`) +- **Glow+grain + pure white background** → atmosphere needs depth +- **Industrial mono + serif body** → mono-everywhere or paired w/ extreme grotesque +- **Active bento + static cards** → must move/expand +- **Type-as-hero + decorative imagery** → type IS the image + +## Step 6 — Self-audit before shipping + +Ask before delivering output: + +1. Did I pick a real direction + commit to it? +2. Did I choose the right surface type and density? +3. Did I avoid every item on `web-bans.md`? +4. Real custom typeface (not Inter / Space Grotesk)? +5. Real copy (not lorem / "Built for modern teams")? +6. Real visual content (no ``)? +7. Motion budget matches the product type? +8. Direction-specific reference apps fit-check passed? +9. Accessibility baseline (semantic HTML, focus rings, AA contrast, reduced-motion)? +10. Layout breaks the wrong template for this surface type? +11. Dark mode (if applicable) has warmth/coolness, not just inversion? +12. Mobile/tablet has no page-level horizontal overflow? +13. Does the design show product proof instead of only making claims? +14. Did I choose an interaction budget and reject the wrong motion libraries for this surface? +15. For cinematic pages, did I define key art, section rhythm, typography discipline, and repeated motifs before motion? +16. Did the implementation track fit the interaction model, and did I avoid adding React/dependencies when static code would be enough? +17. Did the design include one tasteful risk plus restraints, instead of random creativity? + +If any "no" — restart that choice, don't ship near-misses. + +## Step 7 — Quality bar reference points + +Default to fitting alongside one of these. Read `../../references/awwwards-ceiling.md` for direction-grouped refs. + +- linear.app — fast, dark, precision +- stripe.com / stripe.com/sessions — gradient mastery +- vercel.com — animated build log hero +- raycast.com — dark craft, micro-interactions +- resend.com — type-driven dev tool benchmark +- liveblocks.io — Awwwards-tier motion +- arc.net / browser.company — consumer feel +- studiofreight.com / lusion.co — interactive studio ceiling +- igloo.inc — 3D Awwwards SOTY-tier +- werkstatt.fyi — brutalist editorial + +## Read also + +- `../../references/design-philosophy.md` — core thesis +- `../../references/web-patterns/*.md` — copy-paste pattern library +- `../../references/ui-patterns/reference-analysis.md` — structure extraction from shipped references +- `../../references/ui-patterns/creative-direction.md` — original art direction, tasteful risk, and constraints +- `../../references/ui-patterns/interaction-techniques.md` — motion, scroll, and interaction decision system +- `../../references/ui-patterns/cinematic-landing-system.md` — campaign page/key art/page rhythm system +- `../../references/ui-patterns/web-implementation-tracks.md` — static/React/Next/Astro stack decisions and dependency safety +- `../../references/web-direction-*.md` — per-direction full implementation +- `../../references/web-fonts.md` — type pairings +- `../../references/web-bans.md` — anti-slop list +- `../../references/web-motion.md` — motion library docs +- `../../references/web-copy-voice.md` — editorial copy patterns +- `../../references/web-svg-illustration.md` — no-image asset generation +- `../../references/web-layouts.md` — layout pattern catalog +- `../../references/awwwards-ceiling.md` — quality bar refs grouped by direction diff --git a/plugins/f0d010c/stark/skills/windows-design/SKILL.md b/plugins/f0d010c/stark/skills/windows-design/SKILL.md new file mode 100644 index 000000000..53c34df4e --- /dev/null +++ b/plugins/f0d010c/stark/skills/windows-design/SKILL.md @@ -0,0 +1,140 @@ +--- +name: windows-design +description: Use when the user asks for a Windows app, Win11 UI, XAML, Fluent design, WinUI, WPF, PowerToys-style tool, Microsoft Store app, music/photo/creative app, Tauri desktop, Electron desktop, or any Windows desktop deliverable. Builds Windows 11/12 apps across system-like WinUI 3, branded WinUI 3, Tauri 2, and Electron. ALWAYS ask which track first. SKIP when the user explicitly wants only Apple, Android, or web-in-browser. +--- + +# windows-design — pick the track first + +Windows desktop has four distinct tracks. Each has different visual ceilings, different cost. **Ask the user which one before any code.** Do not default. + +## Step 1 (MANDATORY) — Ask the user which track + +Present these four options verbatim. Do not pick for them. + +> Which track do you want for this app? +> +> **1. System-like native (WinUI 3 strict)** — feels like Settings/Calculator/Notepad. Best for: productivity utilities, internal tools, system panels. Visual ceiling: medium. Binary ~30MB. Users who care: Windows power users, IT admins. Examples: PowerToys, Snipping Tool, Sound Recorder. +> +> **2. Branded native (WinUI 3 + branded Fluent)** — native chrome (Mica, Snap Layouts, ThemeResource auto dark/light/HC) but bespoke content surface (custom accent, custom display font, hero atmospheres, magazine layouts). Best for: consumer apps that want fit-in *and* identity. Visual ceiling: high but XAML-bound. Binary ~30MB. Examples: Apple Music for Windows, Files (community), Microsoft Photos rewrite, DevHome. +> +> **3. Tauri 2 + React/Tailwind/Motion** — same React code as Electron but uses Windows' built-in WebView2 instead of bundled Chromium. Full visual freedom (mesh gradients, custom motion, real imagery, anything CSS can do). Binary ~5–10MB. RAM ~30–80MB. Mica still available via Tauri API. Examples: Cap, Spacedrive, ClashVerge, Pot. +> +> **4. Electron + React/Tailwind/Motion** — bundles full Chromium. Same dev experience as Tauri but heavier. Binary ~150–250MB. RAM ~300–500MB. Largest ecosystem, every dev knows it. Examples: Spotify, Discord, VSCode, Slack, Notion, Figma desktop, Claude desktop, ChatGPT desktop. +> +> Which? Or describe priorities (binary size, visual ambition, brand vs fit-in) and I'll pick. + +If the user has already given enough signal in the brief (e.g. "I want a system tray utility" → 1; "I want it to look like Awwwards site" → 3; "Spotify-style" → 3 or 4), state your pick + reasoning in one sentence and proceed. But if ambiguous, ask. + +## Step 1b — Once picked, route + +| Track | Reference docs | Default stack | +|---|---|---| +| 1. System-like WinUI 3 | `../../references/fluent-design.md` | WinUI 3 + WinAppSDK 1.8 + CommunityToolkit.Mvvm + SettingsControls | +| 2. Branded WinUI 3 | `../../references/fluent-design.md` + `../../references/branded-fluent.md` | Same as 1 + custom accent override + embedded display font + bespoke surfaces | +| 3. Tauri 2 + Web | `../../references/web-fonts.md` + `../../references/web-motion.md` + `../../references/web-bans.md` + `../../references/awwwards-ceiling.md` | React 19 + Tailwind v4 + Motion (motion.dev) + Tauri 2 shell | +| 4. Electron + Web | Same as 3 | React 19 + Tailwind v4 + Motion + Electron shell + electron-builder | + +For tracks 3 and 4, the web design rules from `web-design` SKILL apply — same anti-slop ban list, same typography curation, same aesthetic direction discipline. + +## Step 1c — UI decision brief + +Before code, read: + +- `../../references/ui-patterns/surface-taxonomy.md` +- `../../references/ui-patterns/ui-decision-brief.md` +- `../../references/ui-patterns/visual-hierarchy.md` +- `../../references/ui-patterns/motion-budget.md` + +Write the UI decision brief and adapt it to the selected Windows track. Windows utilities and admin tools should favor operational density, stable navigation, SettingsCard/NavigationView idioms, and low motion. Branded consumer apps may use richer content surfaces, but native chrome, Mica/Acrylic rules, Segoe UI Variable, and Fluent icons still apply. + +## Step 2a — Branded vs system-like (only if track 1 or 2 picked) + +Track 1 = system-like. Track 2 = branded. The user already picked. Skip to step 2. + +For reference: branded means native chrome + bespoke content surface. Read `../../references/branded-fluent.md`. + +## Step 2 — WinUI 3 idioms + +Every Win11 app must: +- Extend the title bar into the client area via `AppWindow.TitleBar` API (preserve Snap Layouts hover) +- Apply **Mica** as the top-level window backdrop (`SystemBackdrop="Mica"`) — opaque, desktop-tinted +- Apply **Acrylic** only to transient surfaces: flyouts, command bars, menus +- Use **Mica Alt** for tabbed apps (Terminal, Edge, Files) +- Use 8px corner radius on windows, 4px on controls, 0px in dense grids +- Use **tonal elevation** (background brush shifts) — never CSS-style drop shadows +- Wire light/dark via `ThemeResource` brushes, never hex literals + +**Reveal effect** is deprecated in Win11 styling. Do not generate it. + +## Step 3 — Typography & icons + +- **Segoe UI Variable** is the only correct face. Wire variable axes (wght 100–700, optical size). Never Segoe UI plain. +- **Segoe Fluent Icons** font for iconography. 1 epx monoline. Sizes: 16/20/24/32/40/48/64. +- For body text in productivity: weight 400, size 14, line height 20. For headlines: optical size adjusts automatically — let it. + +## Step 4 — Layout components (use these, not custom) + +| Need | Use | +|---|---| +| Top-level navigation | `NavigationView` (Left, LeftCompact, Top modes) | +| Settings | `SettingsCard` (CommunityToolkit.WinUI.Controls.SettingsControls) | +| Inline alert | `InfoBar` (Severity: Informational/Success/Warning/Error) | +| Coachmark | `TeachingTip` | +| Disclosure | `Expander` | +| Path / breadcrumb | `BreadcrumbBar` | +| Tabbed segment toggle | `SelectorBar` | + +Refer to **WinUI Gallery** (https://github.com/microsoft/WinUI-Gallery) for canonical control usage. When generating, mirror its patterns exactly. + +## Step 5 — Architecture + +- **CommunityToolkit.Mvvm** (`[ObservableProperty]`, `[RelayCommand]`) — never raw `INotifyPropertyChanged` +- DI via `Microsoft.Extensions.Hosting` +- Settings persistence via `Windows.Storage.ApplicationData.Current.LocalSettings` or `Microsoft.UI.Xaml.Settings` +- Localization via `.resw` resource files (not hardcoded strings) + +## Step 6 — Anti-slop ban list (Windows-specific) + +Reject all of these: + +- Inter / Roboto / system-ui on native chrome — only Segoe UI Variable +- CSS-style `box-shadow` — use tonal elevation brushes (`LayerFillColorDefaultBrush` etc.) +- Custom hamburger menu where `NavigationView` belongs +- Acrylic on long-lived window backgrounds (use Mica) +- Mica on flyouts (use Acrylic) +- Hardcoded hex colors — breaks dark mode + high contrast. ThemeResource only. +- Hand-rolled title bar that breaks Snap Layouts hover +- Square 90° corners +- Material Design ripples +- iOS-style segmented controls with sliding pill (use SelectorBar instead) +- Bottom tab bars (Android idiom) +- Custom scrollbars that override `ScrollViewer` (breaks dynamic thinning) +- FontAwesome / Material Symbols icons (use Segoe Fluent Icons) +- Marketing-page spacing in productivity/admin tools +- Decorative cards replacing SettingsCard, table/list, or master-detail surfaces + +## Step 7 — Reference apps to emulate + +- **Files** (files.community) — Mica + tabs + dual-pane + command palette +- **PowerToys** (recently redesigned by Niels Laute) — canonical NavigationView + InfoBar settings shell +- **Windows Terminal** — title-bar tab integration, JSON theming +- **Microsoft Photos (2024 rewrite)** — WinUI 3 + AI surfaces +- **Snipping Tool / Clipchamp** — modern command bar + teaching tips +- **DevHome** — dashboard widget pattern +- **Notepad (rewrite)** — minimal Fluent restraint + +## Step 8 — Tokens & assets + +- Token JSON (DTCG): see `../../assets/tokens/fluent-2.json` shipped with this plugin +- Fluent 2: https://fluent2.microsoft.design +- Win design downloads (Figma + icons + Segoe): https://learn.microsoft.com/windows/apps/design/downloads +- WinUI source: https://github.com/microsoft/microsoft-ui-xaml + +Read `../../references/fluent-design.md` for deep token + spacing reference. + +## Step 9 — Fidelity tradeoffs to communicate + +When the user picks a non-native stack, **state the loss explicitly** in one line: +- Tauri 2: "~3MB binary, but WebView2 chrome — Mica still works via window-backdrop API but font rendering and focus rings will look subtly off vs WinUI 3." +- Avalonia: "Cross-platform but Fluent theme is custom-drawn, not 1:1 with Win11." +- Electron: "Don't. Use Tauri 2 if web stack is mandated." diff --git a/scripts/generate_plugins_json.py b/scripts/generate_plugins_json.py index e8414da75..052743383 100644 --- a/scripts/generate_plugins_json.py +++ b/scripts/generate_plugins_json.py @@ -193,6 +193,14 @@ def collect_selected_paths( if isinstance(value, str): add_recursive_selection(selected, all_names, plugin_root, value) + include = manifest.get("include") + if isinstance(include, str): + add_recursive_selection(selected, all_names, plugin_root, include) + elif isinstance(include, list): + for value in include: + if isinstance(value, str): + add_recursive_selection(selected, all_names, plugin_root, value) + interface = manifest.get("interface") if isinstance(interface, dict): for key in ("composerIcon", "logo"):