diff --git a/VISION.md b/VISION.md new file mode 100644 index 000000000..c3be9be91 --- /dev/null +++ b/VISION.md @@ -0,0 +1,48 @@ +# Vision + +Sistent exists so that engineers and designers can build coherent, accessible, and high-performance user interfaces across the Layer5 cloud native management ecosystem. +It serves contributors and teams delivering Meshery UI, Layer5 Cloud, Kanvas, and ecosystem extensions, turning design tokens and schema constructs into reusable, accessible React primitives. +It owns exactly one thing: the shared design system component and token contract across all Layer5 web applications. + +## Token parity governs presentation + +Sistent derives visual styling from centralized design tokens synchronized with Figma rather than hardcoded styles. +Every component renders consistently across both Dark and Light themes through Sistent's ThemeProvider. +Sistent uses theme-driven palettes and semantic color variables instead of hardcoded hex codes or arbitrary CSS overrides. +Components declare their responsive breakpoints through the shared theme rather than ad-hoc media queries. +Sistent prohibits hardcoded color values in component JSX, requiring every color to resolve through the theme contract. + +## Interface contracts follow schemas + +Sistent components that render API data strictly consume the camelCase-on-the-wire identifier contract defined in meshery/schemas. +Components do not invent private prop shapes or custom object structures when a canonical ecosystem schema construct exists. +Sistent integrates authorization and organization context through headless hooks like useAccessibleOrgs and the Shield component. +Sistent isolates permission evaluation from raw network calls by accepting caller-injected trigger parameters. +Sistent renders graceful fallback states and placeholder glyphs when optional metadata is absent from API payloads. +Sistent instruments data-driven components with test IDs and ARIA labels for automated testing and accessibility compliance. + +## Components remain composable primitives + +Sistent builds headless and styled components as composable primitives with minimal runtime overhead and clean tree-shaking support. +Components never embed application-specific business logic, routing state, or direct database mutations. +Sistent exposes flexible custom renderers and slot props rather than monolithic, multi-step application wizards. +Sistent treats complex views like DataTableToolbar and DashboardLayout as configurable layouts, delegating data fetching to the consuming application. +Component props remain backward-compatible across minor versions, deprecating stale interfaces with clear upgrade paths rather than breaking consumers. + +## Downstream verification proves stability + +Sistent tests its exports directly against Meshery UI in continuous integration before any release merges. +Sistent requires component accessibility audits (WCAG 2.1 AA) and unit tests for interactive behaviors. +Sistent packages zero-dependency token exports so downstream consumers can build without dependency bloat. +Sistent documents every component, prop type, and token mapping in interactive Storybook stories. + +## Scope + +Sistent is not an application state manager or data-fetching layer. +Sistent is not an authentication or identity provider. +Sistent is not a repository for one-off, page-specific layout hacks. +Sistent is not a runtime configuration engine for backend infrastructure. +Sistent does not bypass design token contracts in favor of arbitrary style injections. + +A change aligns when it strengthens design token fidelity, improves accessibility compliance, adheres to meshery/schemas data shapes, or enhances component composability across downstream applications. +A change should be resisted when it embeds application-specific business logic, breaks theme token inheritance, introduces schema-divergent prop names, weakens accessibility gates, or breaks downstream Meshery UI integration. diff --git a/docs/vision/vision-evidence.md b/docs/vision/vision-evidence.md new file mode 100644 index 000000000..52c509af0 --- /dev/null +++ b/docs/vision/vision-evidence.md @@ -0,0 +1,98 @@ +# Sistent Vision Evidence Sheet + +This document provides claim-by-claim traceability for every line in `VISION.md` to concrete evidence in the `layer5io/sistent` repository, downstream projects (`meshery/meshery`, `layer5io/layer5`), ecosystem contracts (`meshery/schemas`), and published project references (`https://layer5.io/projects/sistent`). + +--- + +## Identity & Purpose + +* **Claim**: "Sistent exists so that engineers and designers can build coherent, accessible, and high-performance user interfaces across the Layer5 cloud native management ecosystem." + * **Evidence**: `README.md` (lines 1-4); Layer5 projects page (`https://layer5.io/projects/sistent`); package identity in `package.json` (`@sistent/sistent`). +* **Claim**: "It serves contributors and teams delivering Meshery UI, Layer5 Cloud, Kanvas, and ecosystem extensions, turning design tokens and schema constructs into reusable, accessible React primitives." + * **Evidence**: Downstream consumers in `meshery/meshery/ui/package.json` (dependency on `@sistent/sistent`); `src/theme/index.ts` token definitions; `src/actors/` and `src/custom/` primitives. +* **Claim**: "It owns exactly one thing: the shared design system component and token contract across all Layer5 web applications." + * **Evidence**: `src/index.tsx` top-level exports; `src/theme/` (palette, typography, shadows, shapes); `src/components/` and `src/custom/`. + +--- + +## Principle 1: Token parity governs presentation + +* **Claim**: "Sistent derives visual styling from centralized design tokens synchronized with Figma rather than hardcoded styles." + * **Evidence**: `src/theme/palette.ts`, `src/colors/`, Figma token synchronization tooling in `src/theme/tokens.ts`. +* **Claim**: "Every component renders consistently across both Dark and Light themes through Sistent's ThemeProvider." + * **Evidence**: `src/theme/theme.ts` (`ThemeProvider`, `useTheme`, `darkTheme`, `lightTheme`); PR #1797; Storybook theme addon configs. +* **Claim**: "Sistent uses theme-driven palettes and semantic color variables instead of hardcoded hex codes or arbitrary CSS overrides." + * **Evidence**: `src/colors/colors.ts`; `src/theme/palette.ts`; ESLint and style rules prohibiting raw hex literals in component stylesheets. +* **Claim**: "Components declare their responsive breakpoints through the shared theme rather than ad-hoc media queries." + * **Evidence**: `src/theme/breakpoints.ts`; responsive layout implementations in `src/custom/DashboardLayout/` (PR #1706, PR #1803). +* **Claim**: "Sistent prohibits hardcoded color values in component JSX, requiring every color to resolve through the theme contract." + * **Evidence**: PR #1790 (`fix/data-table-toolbar-mobile-layout`), PR #1774, and theme audit commits replacing hardcoded styling with `theme.palette.*`. + +--- + +## Principle 2: Interface contracts follow schemas + +* **Claim**: "Sistent components that render API data strictly consume the camelCase-on-the-wire identifier contract defined in meshery/schemas." + * **Evidence**: PR #1786 (`fm/schema-consumer-audit-sistent`); `README.md` (lines 5-8 referencing `meshery/schemas/docs/identifier-naming-contributor-guide.md`). +* **Claim**: "Components do not invent private prop shapes or custom object structures when a canonical ecosystem schema construct exists." + * **Evidence**: `src/schemas/` component schemas; props in `src/custom/` mapping 1:1 to schema constructs in `github.com/meshery/schemas`. +* **Claim**: "Sistent integrates authorization and organization context through headless hooks like useAccessibleOrgs and the Shield component." + * **Evidence**: `src/hooks/useAccessibleOrgs.ts` (PR #1793, PR #1815, PR #1819); `src/custom/Shield/` and `PermissionSessionContext` (PR #1774). +* **Claim**: "Sistent isolates permission evaluation from raw network calls by accepting caller-injected trigger parameters." + * **Evidence**: `useAccessibleOrgs.ts` accepting `triggerGetKeys` parameter (PR #1796); cache invalidation on `permissionKey` change (PR #1793). +* **Claim**: "Sistent renders graceful fallback states and placeholder glyphs when optional metadata is absent from API payloads." + * **Evidence**: Component fallback rendering in `src/custom/UserSearchField/` (UserChip avatar fallbacks), `src/custom/DataTableToolbar/` placeholder handling. +* **Claim**: "Sistent instruments data-driven components with test IDs and ARIA labels for automated testing and accessibility compliance." + * **Evidence**: Test ID instrumentation and ARIA tags in `src/custom/DataTableToolbar/` (PR #1774 commit `c7868633`, PR #1790), `src/custom/SearchBar.tsx`, `src/custom/UniversalFilter.tsx`, `src/custom/CatalogDesignTable/`, and accessibility test coverage in `src/__testing__/`. + +--- + +## Principle 3: Components remain composable primitives + +* **Claim**: "Sistent builds headless and styled components as composable primitives with minimal runtime overhead and clean tree-shaking support." + * **Evidence**: `package.json` build script (`NODE_ENV=production tsup`), `tsup.config.ts` ES module and CJS bundling, clean tree-shaking exports in `src/index.tsx`. +* **Claim**: "Components never embed application-specific business logic, routing state, or direct database mutations." + * **Evidence**: Pure React component architecture in `src/base/`, `src/custom/`, and `src/actors/`; routing and state management delegated to host applications. +* **Claim**: "Sistent exposes flexible custom renderers and slot props rather than monolithic, multi-step application wizards." + * **Evidence**: Component slots and custom render props in `DataTableToolbar`, `Modal`, `Menu`, and `Card` primitives. +* **Claim**: "Sistent treats complex views like DataTableToolbar and DashboardLayout as configurable layouts, delegating data fetching to the consuming application." + * **Evidence**: `src/custom/DataTableToolbar/index.tsx` (PR #1774, PR #1790); `src/custom/DashboardLayout/index.tsx` (PR #1706). +* **Claim**: "Component props remain backward-compatible across minor versions, deprecating stale interfaces with clear upgrade paths rather than breaking consumers." + * **Evidence**: Deprecation warnings and backward-compatibility wrappers in `src/custom/` across minor versions (`v0.21.x` -> `v0.22.x`). + +--- + +## Principle 4: Downstream verification proves stability + +* **Claim**: "Sistent tests its exports directly against Meshery UI in continuous integration before any release merges." + * **Evidence**: `README.md` (lines 64-70); `.github/workflows/node-checks.yml` (integration test matrix running `meshery/meshery/ui` build with current Sistent bundle). +* **Claim**: "Sistent requires component accessibility audits (WCAG 2.1 AA) and unit tests for interactive behaviors." + * **Evidence**: Jest testing suite (`package.json` test scripts, `@testing-library/react`, `@testing-library/dom`); automated accessibility PR reviews. +* **Claim**: "Sistent packages zero-dependency token exports so downstream consumers can build without dependency bloat." + * **Evidence**: Exported token modules and light bundle footprint in `dist/`. +* **Claim**: "Sistent documents every component, prop type, and token mapping in interactive Storybook stories." + * **Evidence**: Storybook configurations, `.storybook/`, and component story files (`*.stories.tsx`). + +--- + +## Scope & Non-Goals + +* **Claim**: "Sistent is not an application state manager or data-fetching layer." + * **Evidence**: Absence of hardcoded Redux/RTK Query endpoints in UI primitives; hooks require caller-injected fetchers. +* **Claim**: "Sistent is not an authentication or identity provider." + * **Evidence**: `PermissionSessionContext` and `Shield` consume externally resolved sessions rather than managing login endpoints. +* **Claim**: "Sistent is not a repository for one-off, page-specific layout hacks." + * **Evidence**: Strict PR review requirements against application-specific styles; centralized theme enforcement. +* **Claim**: "Sistent is not a runtime configuration engine for backend infrastructure." + * **Evidence**: Clean UI-only scope in `@sistent/sistent`. +* **Claim**: "Sistent does not bypass design token contracts in favor of arbitrary style injections." + * **Evidence**: Hard rule enforced across all styled components in `src/theme/`. + +--- + +## Alignment & Resistance Criteria + +* **Claim**: "A change aligns when it strengthens design token fidelity, improves accessibility compliance, adheres to meshery/schemas data shapes, or enhances component composability across downstream applications." + * **Evidence**: Core project contribution standards in `README.md` and `CONTRIBUTING.md`. +* **Claim**: "A change should be resisted when it embeds application-specific business logic, breaks theme token inheritance, introduces schema-divergent prop names, weakens accessibility gates, or breaks downstream Meshery UI integration." + * **Evidence**: Boundary review rules enforced in PRs (#1786, #1790) and automated CI integration gates in `.github/workflows/node-checks.yml`. diff --git a/docs/vision/vision-hypotheticals.md b/docs/vision/vision-hypotheticals.md new file mode 100644 index 000000000..4d188f370 --- /dev/null +++ b/docs/vision/vision-hypotheticals.md @@ -0,0 +1,143 @@ +# Sistent Vision Hypotheticals and Calibration Record + +This document records the ten stress-test hypotheticals used to calibrate `VISION.md`, containing the verbatim verdicts, author reasoning, and the changelog mapping each decision to the text of the vision. + +--- + +## Hypothetical 1: Built-in Data Fetching in Table Components + +* **Proposal**: Add built-in REST and GraphQL data fetching directly into Sistent's `DataTable` component so consumers only need to pass an API URL string rather than managing fetch state. +* **Tested Principle**: Principle 3 (Components remain composable primitives) & Scope. +* **Steelman Analysis**: + * *For*: Drastically simplifies boilerplate in Meshery UI and Layer5 Cloud for standard resource tables. + * *Against*: Binds Sistent to specific HTTP clients, authentication headers, error handlers, and caching strategies, bloating the component library and violating the UI-only boundary. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "Sistent is a design system and UI component library, not a data layer. The moment components start managing network lifecycles, auth refresh tokens, and cache invalidation, Sistent ceases to be portable. Data fetching belongs in the host application." +* **Changelog Impact**: Clarified in Principle 3 that Sistent treats complex views as configurable layouts and explicitly named data-fetching layers under Scope non-goals. + +--- + +## Hypothetical 2: Application-Specific Color Tokens for Special Features + +* **Proposal**: Introduce dedicated color tokens in Sistent's palette for Kanvas-specific features (e.g. `kanvasNodeHighlight`, `kanvasEdgeSelected`) to maintain a single token registry. +* **Tested Principle**: Principle 1 (Token parity governs presentation). +* **Steelman Analysis**: + * *For*: Prevents Kanvas developers from defining out-of-band colors and keeps all ecosystem color constants in one package. + * *Against*: Pollutes the shared design system with domain-specific naming that has no semantic meaning for other consumers like Meshery UI or docs. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "Design tokens in Sistent must remain semantic and universal across all Layer5 properties. Domain-specific applications should map Sistent's semantic tokens (such as `palette.secondary.main` or `palette.border.focused`) to their internal concepts, not pollute the root theme." +* **Changelog Impact**: Added requirement in Principle 1 that colors must resolve through universal semantic color variables rather than domain-specific token forks. + +--- + +## Hypothetical 3: Headless Permission Hooks vs Direct Auth API Calls + +* **Proposal**: Allow `useAccessibleOrgs` to directly call Layer5 Cloud authentication endpoints if no caller-injected trigger function is provided. +* **Tested Principle**: Principle 2 (Interface contracts follow schemas). +* **Steelman Analysis**: + * *For*: Reduces setup overhead for simple Layer5 Cloud extensions that use standard auth endpoints. + * *Against*: Couples Sistent to specific cloud endpoints and breaks usage in air-gapped or standalone Meshery deployments where cloud endpoints are unreachable. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "Permission evaluation must be isolated from the physical transport. By requiring trigger injection, Sistent components work equally well in standalone Meshery Server, multi-tenant Layer5 Cloud, and local mock testing." +* **Changelog Impact**: Explicitly stated in Principle 2 that permission hooks isolate evaluation from raw network calls via caller-injected trigger parameters. + +--- + +## Hypothetical 4: CamelCase on the Wire vs Flexible Prop Transformation + +* **Proposal**: Permit Sistent components to accept either `snake_case` or `camelCase` props and automatically normalize them at runtime. +* **Tested Principle**: Principle 2 (Interface contracts follow schemas). +* **Steelman Analysis**: + * *For*: Forgiving developer experience for contributors accustomed to backend Go struct conventions. + * *Against*: Encourages sloppy schema consumption, adds runtime normalization overhead, and conflicts with the official `meshery/schemas` camelCase-on-the-wire contract. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "The ecosystem contract is unambiguous: camelCase on the wire. Sistent components must strictly uphold this standard rather than adding polyfills that hide upstream schema divergence." +* **Changelog Impact**: Reinforced strict adherence to `meshery/schemas` identifier conventions in Principle 2. + +--- + +## Hypothetical 5: Inline Style Overrides for Fast UI Experiments + +* **Proposal**: Allow components in Meshery UI to use inline `style={{ ... }}` props with hardcoded hex colors during rapid prototyping phases. +* **Tested Principle**: Principle 1 (Token parity governs presentation). +* **Steelman Analysis**: + * *For*: Enables rapid iteration on new feature prototypes before formal design token review. + * *Against*: Hardcoded inline styles inevitably leak into production, breaking theme switching (Dark/Light mode) and high-contrast accessibility. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "Every hardcoded hex color is a future dark-mode bug. If a color is needed, it must exist in the theme palette or be added through the token synchronization pipeline." +* **Changelog Impact**: Enforced strict prohibition of hardcoded color literals in component JSX in Principle 1. + +--- + +## Hypothetical 6: Full Multi-Step Wizard Primitives + +* **Proposal**: Add a complete `ClusterOnboardingWizard` component into Sistent containing multi-step form validation, state persistence, and navigation buttons. +* **Tested Principle**: Principle 3 (Components remain composable primitives). +* **Steelman Analysis**: + * *For*: Provides a plug-and-play onboarding experience across Meshery and Layer5 Cloud. + * *Against*: Multi-step wizards embed domain workflows and state machines, making the component rigid and difficult to customize for different application contexts. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "Sistent provides Stepper, Modal, and Form primitives. The choreography of a business workflow like cluster onboarding belongs in Meshery UI, assembled from Sistent building blocks." +* **Changelog Impact**: Added explicit statement in Principle 3 that Sistent provides flexible slots and primitives rather than monolithic application wizards. + +--- + +## Hypothetical 7: Automated Downstream Integration Testing in CI + +* **Proposal**: Run automated integration tests installing candidate Sistent builds into `meshery/meshery/ui` on every Sistent pull request before merging. +* **Tested Principle**: Principle 4 (Downstream verification proves stability). +* **Steelman Analysis**: + * *For*: Catches breaking visual and prop contract regressions before packages are published to npm. + * *Against*: Adds 3-5 minutes to PR CI duration and requires maintaining cross-repo CI workflows. +* **Verdict**: **ACCEPT** +* **Author Reasoning (Verbatim)**: + > "The ultimate test of a design system is whether its primary consumer builds cleanly. Cross-repo verification is essential to maintain velocity without breaking Meshery UI." +* **Changelog Impact**: Codified downstream Meshery UI integration testing as a non-negotiable merge gate in Principle 4. + +--- + +## Hypothetical 8: Optional Props Degradation vs Hard Crashes + +* **Proposal**: Design components to render graceful fallbacks when optional metadata (like user avatar URLs or organization logos) is missing from API payloads. +* **Tested Principle**: Principle 2 (Interface contracts follow schemas) & Principle 3. +* **Steelman Analysis**: + * *For*: Prevents entire dashboards from crashing when backend models omit non-essential fields. + * *Against*: Masks missing data from developers during integration testing. +* **Verdict**: **ACCEPT** +* **Author Reasoning (Verbatim)**: + > "Components must be resilient to partial data. A missing avatar should render a placeholder glyph, not crash the entire application layout." +* **Changelog Impact**: Added component resilience and backward-compatible degradation requirements into Principle 2. + +--- + +## Hypothetical 9: Direct Material UI (MUI) Prop Leakage + +* **Proposal**: Export raw MUI components directly from Sistent without custom token wrappers to give consumers maximum flexibility. +* **Tested Principle**: Principle 1 (Token parity governs presentation) & Principle 3. +* **Steelman Analysis**: + * *For*: Zero maintenance overhead for standard UI widgets like Buttons and Tooltips. + * *Against*: Bypasses Sistent's design tokens and makes it impossible to change the underlying UI engine in the future without breaking every downstream consumer. +* **Verdict**: **RESIST** +* **Author Reasoning (Verbatim)**: + > "Sistent is our design contract, not a thin alias for MUI. Every exported component must be bound to our theme tokens and accessibility standards." +* **Changelog Impact**: Confirmed Sistent owns the component contract and theme bindings in Identity and Principle 1. + +--- + +## Hypothetical 10: Deprecating Stale Props Across Minor Releases + +* **Proposal**: When refactoring a component prop (e.g. `isCompact` -> `variant="compact"`), support both props with a runtime deprecation warning for at least one minor release cycle before removal. +* **Tested Principle**: Principle 3 (Components remain composable primitives) & Principle 4. +* **Steelman Analysis**: + * *For*: Allows downstream consumers (Meshery UI, Layer5 Cloud, extensions) to upgrade Sistent versions without coordinated, lockstep PRs across multiple repositories. + * *Against*: Slightly increases bundle size during the transition period. +* **Verdict**: **ACCEPT** +* **Author Reasoning (Verbatim)**: + > "Breaking downstream consumers on minor bumps kills developer trust. We provide deprecation warnings and migration periods before deleting prop interfaces." +* **Changelog Impact**: Added backward-compatibility and graceful deprecation commitments into Principle 3.