tevra-design-kit 0.0.0-stage → 1.0.0

package/references/accessibility/manual-checklist.md

@@ -0,0 +1,3 @@
+# Manual accessibility evidence
+
+Record route/state, viewport, tool/version and result for keyboard order, visible focus, focus restoration, Escape behavior, zoom/reflow, announcements, content meaning and screen-reader navigation. Record target-size exceptions and contrast pairs requiring interpretation. Automated axe results do not establish full WCAG compliance. VoiceOver/TalkBack and native test tools are needed for native surfaces.

package/references/color-systems/semantic-color.md

@@ -0,0 +1,3 @@
+# Color contracts
+
+Separate raw palette values from text, surface, focus, success and danger roles. Check real pairs with contrast tools in each theme and state. Information must not depend on color alone. Native and web color pipelines may differ; validate on the target device. Exported foundations are proposals, not a brand migration.

package/references/design-principles/decision-making.md

@@ -0,0 +1,3 @@
+# Evidence and design judgment
+
+Start with the user task, existing system and real content. Use references to answer a decision, not to collect styles. Prefer clear hierarchy, deliberate grouping and meaningful contrast. Aesthetic heuristics need context; gradients, cards, rounding and decorative motion are not universally wrong. Record why a direction serves the task and which decisions are approved.

package/references/frameworks/nextjs.md

@@ -0,0 +1,3 @@
+# Next.js
+
+Read the installed version and retain App/Pages Router ownership. Keep data access and secrets on the server; make the interactive client boundary as small as the task permits. Do not change caching semantics during a visual task. Provide loading/error states with project patterns. Build and run the actual application before browser review. Reference: https://nextjs.org/docs/app/getting-started/server-and-client-components

package/references/frameworks/react-native-expo.md

@@ -0,0 +1,3 @@
+# React Native / Expo
+
+Preserve native navigation and data ownership. Use accessibilityRole/Label/State, native focus conventions, safe-area APIs and platform reduced-motion settings. Check font scaling, touch targets and VoiceOver/TalkBack. Use device/simulator tooling such as existing native test suites; Playwright only validates web output, never native views. References: https://reactnative.dev/docs/accessibility and https://docs.expo.dev/guides/accessibility/

package/references/frameworks/react.md

@@ -0,0 +1,3 @@
+# React
+
+Read project rules and its React best-practices skill first. Keep state with its owner; derive values during render. Effects synchronize external systems and require cleanup; abort stale requests. Use semantic inputs and stable IDs, preserve public props and data contracts. Test actual form and keyboard behavior. Reference: https://react.dev/learn/thinking-in-react

package/references/frameworks/sveltekit.md

@@ -0,0 +1,3 @@
+# SvelteKit
+
+Use installed Svelte conventions. Svelte 5 runes belong in supported component/module contexts. Keep request-specific state out of shared server modules; preserve load/actions and SSR boundaries. Use form semantics and explicit error handling; clean up subscriptions. Build with the chosen adapter and check the served output. Reference: https://svelte.dev/docs/kit/creating-a-project

package/references/frameworks/vue.md

@@ -0,0 +1,3 @@
+# Vue
+
+Keep props/emits contracts stable, use component-owned reactive state and computed derivations, clean up watchers/listeners and preserve async cancellation. Label v-model controls and show validation errors without discarding input. Validate with the project build and browser interaction tests. Reference: https://vuejs.org/guide/essentials/forms.html

package/references/typography/scales.md

@@ -0,0 +1,3 @@
+# Typography
+
+Inventory installed fonts, licenses, supported glyphs and reading roles. Build body, label and heading roles around the content. Test Vietnamese diacritics, long words, numbers, zoom and fallback loading. Use fluid sizes with readable bounds or explicit project breakpoints. Do not load remote fonts merely to decorate a local workflow.

package/references/ux-patterns/README.md

@@ -0,0 +1,7 @@
+# Local research index
+
+`catalog.json` is a deliberately small maintained knowledge base, not a claim to cover every industry. Each record has stable ID, category, search tags, recommendation, source, confidence and license. Three short UX recommendations are adapted from UI/UX Pro Max under its bundled MIT notice; other records are original Tevra guidance.
+
+The TypeScript search engine builds document term counts and corpus document frequencies in memory on each query. Unicode word tokenization, case folding and BM25 (`k1=1.2`, `b=0.75`) rank exact terms; ties use stable IDs. No remote search, embedding service or persistent private index is used. Domain filtering occurs before scoring. Scores describe relevance only. Empty matches remain empty rather than inventing a recommendation.
+
+Add/update records with provenance and focused tags, then add a meaningful relevance test. Current-trend claims need a separately dated source. Framework guidance is maintained in `references/frameworks/` and loaded only for the selected stack.

package/references/ux-patterns/UPSTREAM-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Next Level Builder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/references/ux-patterns/catalog.json

@@ -0,0 +1,221 @@
+[
+  {
+    "id": "upstream-active-navigation",
+    "category": "ux",
+    "tags": [
+      "navigation",
+      "active",
+      "current",
+      "điều hướng"
+    ],
+    "recommendation": "Indicate the current location beyond color alone.",
+    "source": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/src/ui-ux-pro-max/data/ux-guidelines.csv",
+    "confidence": "reported",
+    "license": "MIT"
+  },
+  {
+    "id": "upstream-reduced-motion",
+    "category": "motion",
+    "tags": [
+      "animation",
+      "motion",
+      "reduced",
+      "chuyển động"
+    ],
+    "recommendation": "Respect reduced-motion preferences while retaining feedback.",
+    "source": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/src/ui-ux-pro-max/data/ux-guidelines.csv",
+    "confidence": "reported",
+    "license": "MIT"
+  },
+  {
+    "id": "upstream-loading-feedback",
+    "category": "ux",
+    "tags": [
+      "loading",
+      "async",
+      "feedback",
+      "đang tải"
+    ],
+    "recommendation": "Show progress feedback while work is pending.",
+    "source": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/src/ui-ux-pro-max/data/ux-guidelines.csv",
+    "confidence": "reported",
+    "license": "MIT"
+  },
+  {
+    "id": "form-recovery",
+    "category": "ux",
+    "tags": [
+      "form",
+      "error",
+      "validation",
+      "mobile",
+      "biểu mẫu",
+      "lỗi"
+    ],
+    "recommendation": "Keep entered values, associate errors with fields, and focus a meaningful summary after failed submission.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "commerce-choice",
+    "category": "product",
+    "tags": [
+      "commerce",
+      "pricing",
+      "card",
+      "checkout",
+      "thanh toán"
+    ],
+    "recommendation": "Present comparable plan terms and a clear purchase action while preserving currency and selected identifiers.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "dashboard-decisions",
+    "category": "product",
+    "tags": [
+      "dashboard",
+      "analytics",
+      "chart",
+      "table",
+      "bảng"
+    ],
+    "recommendation": "Prioritize the decision users make from the data; provide an accessible tabular alternative to essential charts.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "collaboration-status",
+    "category": "product",
+    "tags": [
+      "collaboration",
+      "editor",
+      "save",
+      "conflict"
+    ],
+    "recommendation": "Distinguish saved, pending and conflicted changes and provide recovery without discarding work.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "editorial-reading",
+    "category": "typography",
+    "tags": [
+      "content",
+      "reading",
+      "serif",
+      "editorial",
+      "font"
+    ],
+    "recommendation": "Use a readable body face with deliberate measure and hierarchy; add a characterful heading face only when it serves the brand.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "interface-type",
+    "category": "typography",
+    "tags": [
+      "dashboard",
+      "sans",
+      "typography",
+      "numbers",
+      "font"
+    ],
+    "recommendation": "Prefer legible UI type and tabular numerals for comparison; validate Vietnamese glyphs and text scaling.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "semantic-color",
+    "category": "color",
+    "tags": [
+      "palette",
+      "light",
+      "dark",
+      "contrast",
+      "color",
+      "màu"
+    ],
+    "recommendation": "Assign semantic text, surface, focus and danger roles before choosing accent colors; test actual contrast pairs in both themes.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "brand-expression",
+    "category": "color",
+    "tags": [
+      "brand",
+      "warm",
+      "professional",
+      "palette"
+    ],
+    "recommendation": "Keep established brand roles and spend the accent on meaningful actions rather than unrelated decoration.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "responsive-comparison",
+    "category": "layout",
+    "tags": [
+      "responsive",
+      "mobile",
+      "table",
+      "overflow",
+      "di động"
+    ],
+    "recommendation": "Preserve meaningful table comparison with intentional scrolling and a visible affordance; do not clip columns to hide overflow.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "dense-workspace",
+    "category": "layout",
+    "tags": [
+      "density",
+      "dashboard",
+      "spacing",
+      "grid"
+    ],
+    "recommendation": "Group by task and frequency, preserve keyboard order and keep important actions readable at narrow widths.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "health-sensitive",
+    "category": "industry",
+    "tags": [
+      "health",
+      "insurance",
+      "medical",
+      "bảo hiểm"
+    ],
+    "recommendation": "Use understandable language and confirmation for consequential choices; domain accuracy needs an authoritative subject-matter source.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  },
+  {
+    "id": "financial-status",
+    "category": "industry",
+    "tags": [
+      "finance",
+      "bank",
+      "money",
+      "currency"
+    ],
+    "recommendation": "Preserve formatting, transaction state and error recovery; never imply a transfer completed before confirmation.",
+    "source": "Tevra original",
+    "confidence": "inferred",
+    "license": "MIT"
+  }
+]

package/registry/capability-ownership.json

@@ -0,0 +1,191 @@
+{
+  "version": 1,
+  "capabilities": [
+    {
+      "id": "ux.research",
+      "primary": "tevra.design-research",
+      "supporting": [],
+      "stage": 1,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "visual.direction",
+      "primary": "tevra.design-direction",
+      "supporting": [
+        "tevra.design-research"
+      ],
+      "stage": 2,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "design.tokens",
+      "primary": "tevra.design-system",
+      "supporting": [],
+      "stage": 3,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "frontend.implementation",
+      "primary": "tevra.ui-builder",
+      "supporting": [
+        "tevra.frontend-review"
+      ],
+      "stage": 4,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "ui.redesign",
+      "primary": "tevra.ui-redesign",
+      "supporting": [],
+      "stage": 5,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "responsive.design",
+      "primary": "tevra.responsive-design",
+      "supporting": [],
+      "stage": 6,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "interaction.motion",
+      "primary": "tevra.interaction-motion",
+      "supporting": [],
+      "stage": 7,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "visual.regression",
+      "primary": "tevra.visual-review",
+      "supporting": [],
+      "stage": 8,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "accessibility",
+      "primary": "tevra.accessibility-qa",
+      "supporting": [],
+      "stage": 9,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "performance",
+      "primary": "tevra.performance-qa",
+      "supporting": [],
+      "stage": 10,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "browser.testing",
+      "primary": "tevra.browser-testing",
+      "supporting": [],
+      "stage": 11,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "frontend.review",
+      "primary": "tevra.frontend-review",
+      "supporting": [],
+      "stage": 12,
+      "constraints": [
+        "preserve-approved-scope"
+      ],
+      "validation": [
+        "artifact-evidence",
+        "scope-preserved"
+      ]
+    },
+    {
+      "id": "component.architecture",
+      "primary": "tevra.frontend-review",
+      "supporting": [
+        "tevra.ui-builder"
+      ],
+      "stage": 4,
+      "constraints": [
+        "existing-framework"
+      ],
+      "validation": [
+        "source-evidence"
+      ]
+    },
+    {
+      "id": "seo",
+      "primary": null,
+      "supporting": [],
+      "stage": 10,
+      "constraints": [
+        "not-automated"
+      ],
+      "validation": [
+        "manual-review-required"
+      ]
+    }
+  ]
+}