@ketvietlab/design-system 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KETVIET JSC, Vietnam
+
+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/README.md

@@ -0,0 +1,48 @@
+# @ketvietlab/design-system
+
+Public server-rendered components for dense operational applications.
+
+The package depends only on `@ketvietlab/ketjs-view`. It does not know about
+KetSuite routes, translators, models, functions, sessions, or deployments.
+
+```ts
+// File: src/ui/orders.tsx
+import { AppShell, Button, DataTable, FormPage, ListPage, Page, Section, Surface } from '@ketvietlab/design-system'
+```
+
+Load `@ketvietlab/design-system/styles.css` and put `data-kv-design-system` on the
+application root. Components own their markup and `data-ui` hooks; applications
+provide business data and translated labels.
+
+The catalogue is isolated behind `@ketvietlab/design-system/catalogue`, so the
+production entry point does not load its specimen data or catalogue chrome.
+
+Run the component catalogue from the repository root:
+
+```bash
+npm run design:system
+```
+
+Then open `http://127.0.0.1:4100`.
+
+The contract is intentionally strict:
+
+- Inter is the only UI typeface;
+- sidebar, main application region, and context right rail use `--kv-radius-app-region` (`0`);
+- independent objects such as KPI cards use the shared 3–12px radius scale;
+- a page is never wrapped in one large card;
+- record sections and rail sections use low-contrast separators instead of nested cards;
+- component CSS consumes semantic/component roles, not numbered palette swatches.
+
+The public entry exports actions, status and feedback objects, fields, navigation,
+tabs, progress, layout primitives, the three-region app shell, page/record layouts,
+the canonical list-page and form-page compositions, data tables, forms, and modal sheets. Use
+`ListPage` for operational collections: applications provide translated identity,
+URL-driven controls and result content while the pattern keeps header, controls,
+status, body and footer in one stable order. The primary action stays beside the
+title, while result status and controls share one command bar. Use `FormPage` for
+create and edit screens: the primary decision stays beside record identity, the
+business form keeps one reading column, and durable facts may occupy the optional
+context rail. Form fields keep labels on the left and controls on the right at
+every viewport; responsive layouts tighten those columns instead of changing the
+reading direction. Every supported state appears in the catalogue.

package/dist/catalogue/catalogue.css

@@ -0,0 +1,344 @@
+@layer ket.app {
+  body:has([data-ui="catalogue-surface-preview"]) {
+    margin: 0;
+  }
+
+  [data-ui="catalogue-surface-preview"] {
+    min-width: 0;
+  }
+  body:has([data-ui="catalogue"]) {
+    margin: 0;
+    background: var(--kv-color-canvas);
+  }
+
+  :where([data-kv-design-system])[data-ui="catalogue"] {
+    display: grid;
+    min-height: 100dvh;
+    grid-template-columns: 15rem minmax(0, 1fr);
+    background:
+      linear-gradient(var(--kv-color-line) 1px, transparent 1px),
+      linear-gradient(90deg, var(--kv-color-line) 1px, transparent 1px), var(--kv-color-canvas);
+    background-size: 4rem 4rem;
+    background-position: -1px -1px;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-rail"] {
+    position: sticky;
+    top: 0;
+    display: flex;
+    height: 100dvh;
+    flex-direction: column;
+    padding: var(--kv-space-6) var(--kv-space-4);
+    border-right: 1px solid var(--kv-color-line);
+    background: color-mix(in srgb, var(--kv-color-canvas-raised) 94%, transparent);
+    backdrop-filter: blur(14px);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-brand"] {
+    display: flex;
+    align-items: center;
+    gap: var(--kv-space-3);
+    color: var(--kv-color-ink);
+    font-family: var(--kv-font-display);
+    font-size: var(--kv-text-md);
+    text-decoration: none;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-brand"] > span {
+    display: grid;
+    width: 2rem;
+    height: 2rem;
+    place-items: center;
+    border-radius: 50% 50% 50% var(--kv-radius-xs);
+    background: var(--kv-color-accent);
+    color: var(--kv-color-on-accent);
+    font-family: var(--kv-font-sans);
+    font-size: var(--kv-text-sm);
+    font-weight: 850;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-kicker"] {
+    margin: var(--kv-space-5) 0 var(--kv-space-3);
+    color: var(--kv-color-ink-muted);
+    font-family: var(--kv-font-mono);
+    font-size: var(--kv-text-xs);
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-nav"] {
+    display: grid;
+    gap: var(--kv-space-1);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-nav-group"] {
+    display: flex;
+    min-height: 2.25rem;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--kv-space-3);
+    padding-inline: var(--kv-space-3);
+    border-radius: var(--kv-radius-sm);
+    color: var(--kv-color-ink-secondary);
+    font-size: var(--kv-text-sm);
+    font-weight: 650;
+    text-decoration: none;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-nav-group"]:hover {
+    background: var(--kv-color-surface-hover);
+    color: var(--kv-color-ink);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-nav-count"] {
+    color: var(--kv-color-ink-muted);
+    font-family: var(--kv-font-mono);
+    font-size: var(--kv-text-xs);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-main"] {
+    width: min(100%, 96rem);
+    min-width: 0;
+    padding: var(--kv-space-10) clamp(var(--kv-space-5), 4vw, var(--kv-space-12)) 8rem;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-hero"] {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(17rem, 0.45fr);
+    gap: var(--kv-space-8);
+    align-items: end;
+    min-height: 19rem;
+    margin-bottom: 5rem;
+    padding: clamp(var(--kv-space-6), 5vw, var(--kv-space-12));
+    border: 1px solid var(--kv-color-line-strong);
+    border-radius: var(--kv-radius-lg);
+    background:
+      radial-gradient(
+        circle at 88% 12%,
+        color-mix(in srgb, var(--kv-color-accent) 20%, transparent),
+        transparent 32%
+      ),
+      linear-gradient(142deg, var(--kv-color-surface), var(--kv-color-canvas-raised));
+    box-shadow: var(--kv-shadow-float);
+    overflow: hidden;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-hero"] [data-ui="catalogue-kicker"] {
+    margin-top: 0;
+    color: var(--kv-color-accent);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-title"] {
+    max-width: 13ch;
+    margin-bottom: var(--kv-space-4);
+    font-family: var(--kv-font-display);
+    font-size: var(--kv-text-3xl);
+    font-weight: var(--kv-weight-semibold);
+    letter-spacing: -0.035em;
+    line-height: 0.98;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-intro"] {
+    max-width: 52rem;
+    margin-bottom: 0;
+    color: var(--kv-color-ink-secondary);
+    font-size: var(--kv-text-md);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-controls"] {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 1px;
+    padding: 1px;
+    border-radius: var(--kv-radius-sm);
+    background: var(--kv-color-line);
+    overflow: hidden;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-controls"] > span {
+    grid-column: 1 / -1;
+    padding: var(--kv-space-2) var(--kv-space-3);
+    background: var(--kv-color-surface-subtle);
+    color: var(--kv-color-ink-muted);
+    font-family: var(--kv-font-mono);
+    font-size: var(--kv-text-xs);
+    font-weight: 800;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-controls"] > a {
+    padding: var(--kv-space-2);
+    background: var(--kv-color-surface);
+    color: var(--kv-color-ink-secondary);
+    font-size: var(--kv-text-xs);
+    font-weight: 700;
+    text-align: center;
+    text-decoration: none;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-controls"] > a:hover,
+  :where([data-kv-design-system]) [data-ui="catalogue-controls"] > a[aria-current="page"] {
+    background: var(--kv-color-accent-soft);
+    color: var(--kv-color-accent);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-group"] {
+    display: grid;
+    gap: var(--kv-space-4);
+    margin-top: 5rem;
+    scroll-margin-top: var(--kv-space-5);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-group-head"] {
+    display: grid;
+    grid-template-columns: minmax(12rem, 0.55fr) minmax(0, 1fr);
+    gap: var(--kv-space-8);
+    align-items: end;
+    padding-bottom: var(--kv-space-4);
+    border-bottom: 1px solid var(--kv-color-line-strong);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-group-head"] h2 {
+    margin-bottom: 0;
+    font-family: var(--kv-font-display);
+    font-size: 1.8rem;
+    font-weight: 650;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-group-head"] [data-ui="catalogue-kicker"] {
+    margin: 0 0 var(--kv-space-1);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-group-head"] > p {
+    max-width: 48rem;
+    margin-bottom: 0;
+    color: var(--kv-color-ink-secondary);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-specimen"] {
+    min-width: 0;
+    border: 1px solid var(--kv-color-line);
+    border-radius: var(--kv-radius-md);
+    background: var(--kv-color-canvas-raised);
+    scroll-margin-top: var(--kv-space-5);
+    overflow: hidden;
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-specimen-head"] {
+    display: flex;
+    align-items: start;
+    justify-content: space-between;
+    gap: var(--kv-space-4);
+    padding: var(--kv-space-4) var(--kv-space-5);
+    border-bottom: 1px solid var(--kv-color-line);
+    background: var(--kv-color-surface-subtle);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-specimen-name"] {
+    margin-bottom: 0;
+    font-size: var(--kv-text-base);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-specimen-description"] {
+    max-width: 52rem;
+    margin: var(--kv-space-1) 0 0;
+    color: var(--kv-color-ink-muted);
+    font-size: var(--kv-text-sm);
+  }
+
+  :where([data-kv-design-system]) [data-ui="catalogue-stage"] {
+    min-width: 0;
+    padding: clamp(var(--kv-space-4), 4vw, var(--kv-space-8));
+    background: radial-gradient(
+      circle at 1px 1px,
+      color-mix(in srgb, var(--kv-color-line) 74%, transparent) 1px,
+      transparent 0
+    );
+    background-size: 1rem 1rem;
+  }
+
+  :where([data-kv-design-system]) [data-ui="shell-demo-sidebar"],
+  :where([data-kv-design-system]) [data-ui="shell-demo-rail"] {
+    display: grid;
+    align-content: start;
+    gap: var(--kv-space-5);
+    padding: var(--kv-space-5) var(--kv-space-4);
+  }
+
+  :where([data-kv-design-system]) [data-ui="shell-demo-rail"] > p:not([data-ui="catalogue-kicker"]) {
+    margin: calc(-1 * var(--kv-space-3)) 0 0;
+    color: var(--kv-text-muted);
+    font-size: var(--kv-text-sm);
+  }
+
+  @media (max-width: 64rem) {
+    :where([data-kv-design-system])[data-ui="catalogue"] {
+      grid-template-columns: 1fr;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-rail"] {
+      position: sticky;
+      z-index: 10;
+      top: 0;
+      height: auto;
+      flex-direction: row;
+      align-items: center;
+      gap: var(--kv-space-4);
+      padding: var(--kv-space-3) var(--kv-space-4);
+      border-right: 0;
+      border-bottom: 1px solid var(--kv-color-line);
+      overflow-x: auto;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-rail"] > [data-ui="catalogue-kicker"] {
+      display: none;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-nav"] {
+      display: flex;
+      flex: 1;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-nav-group"] {
+      flex: 0 0 auto;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-main"] {
+      padding-top: var(--kv-space-6);
+    }
+  }
+
+  @media (max-width: 48rem) {
+    :where([data-kv-design-system]) [data-ui="catalogue-hero"],
+    :where([data-kv-design-system]) [data-ui="catalogue-group-head"] {
+      grid-template-columns: 1fr;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-hero"] {
+      min-height: auto;
+      margin-bottom: var(--kv-space-12);
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-specimen-head"] {
+      align-items: stretch;
+      flex-direction: column;
+    }
+  }
+
+  @media (max-width: 30rem) {
+    :where([data-kv-design-system]) [data-ui="catalogue-brand"] strong,
+    :where([data-kv-design-system]) [data-ui="catalogue-nav-count"] {
+      display: none;
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-main"] {
+      padding-inline: var(--kv-space-3);
+    }
+
+    :where([data-kv-design-system]) [data-ui="catalogue-stage"] {
+      padding: var(--kv-space-3);
+    }
+  }
+}

package/dist/catalogue/index.d.ts

@@ -0,0 +1,22 @@
+import type { JSXChild, TemplateResult } from '@ketvietlab/ketjs-view';
+export { PageSurfacePreview, surfaceKinds, surfaceStates } from './page-surfaces.tsx';
+export type ComponentExample = {
+    id: string;
+    name: string;
+    description: string;
+    render: () => JSXChild;
+};
+export type ComponentGroup = {
+    id: string;
+    name: string;
+    description: string;
+    examples: readonly ComponentExample[];
+};
+export declare const componentGroups: readonly ComponentGroup[];
+export declare const CATALOGUE_HOOKS: readonly ['catalogue-surface-preview', 'catalogue', 'catalogue-rail', 'catalogue-brand', 'catalogue-kicker', 'catalogue-nav', 'catalogue-nav-group', 'catalogue-nav-count', 'catalogue-main', 'catalogue-hero', 'catalogue-title', 'catalogue-intro', 'catalogue-controls', 'catalogue-group', 'catalogue-group-head', 'catalogue-specimen', 'catalogue-specimen-head', 'catalogue-specimen-name', 'catalogue-specimen-description', 'catalogue-stage'];
+export declare const CatalogueHead: () => TemplateResult;
+export declare const CataloguePage: (props?: {
+    theme?: 'light' | 'dark' | 'system';
+    density?: 'compact' | 'default' | 'comfortable';
+}) => TemplateResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/catalogue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/design-system/src/catalogue/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAkBtE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAErF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,QAAQ,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;CACtC,CAAA;AAkBD,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EA8sBpD,CAAA;AAED,eAAO,MAAM,eAAe,YAC1B,2BAA2B,EAC3B,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,EACzB,gCAAgC,EAChC,iBAAiB,CACT,CAAA;AAEV,eAAO,MAAM,aAAa,QAAO,cACgH,CAAA;AAEjJ,eAAO,MAAM,aAAa,WACjB;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;CAAE,KAC9F,cA2GF,CAAA"}