@iyulab/house-style 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.0] - 2026-10-05
+
+First release as a package. Until now `@iyulab/house-style` was only the guide site.
+
+### Added
+
+- **Speaks `@iyulab/components` 2.0's appearance vocabulary** — the guide, the reference app and
+  the example use `appearance` (`plain` for the former `ghost`, `soft` for `filled`), status tags
+  are `soft` with a `dot`, `color="neutral"` is the grey label. Text fields get the same three
+  heights as buttons (28 / 32 / 40) through `size`.
+
+- **The house theme, CSS only, in the `iyu.house` cascade layer** (requires `@iyulab/components`
+  2.0, whose defaults sit in `iyu.base`; unlayered application CSS always wins):
+  - `styles/tokens.css` — warm-grey neutrals, ink primary action, blue reserved for links and
+    focus (`--u-focus-ring-color`), status tints with AA text, canvas vs surface
+    (`--u-canvas-bg-color`), radius 4/6/10, a flat surface lift and one overlay shadow,
+    Pretendard and the 22/18/15/14/13/12/11 type ladder — light and dark. Brand tokens
+    `--hs-brand`, `--hs-brand-soft`, `--hs-brand-ink` (neutral by default).
+  - `styles/components.css` — 28/32/40 buttons, flat cards, side-sheet header and visible body
+    scrollbar, 40px `flex-table` rows with a quiet header and no zebra, page header eyebrow and
+    description, the shell's canvas and page padding.
+  - `styles/patterns.css` — `hs-*` patterns: page head, saved-view tabs with counts, filter bar,
+    stat strip, table card with selection toolbar and pager, plain table with row actions on
+    hover, card and description list, two-column detail, callout (info · success · warning ·
+    danger · note), form sections and fields, side-sheet footer, attribute label, days-left mark.
+  - `styles/tailwind.css` — the Tailwind CSS v4 entry: imports the theme into Tailwind's
+    `components` layer (Tailwind's preflight would otherwise beat the house layer) and maps the
+    roles to utilities. `styles/tailwind-neutrals.css` (opt-in) points Tailwind's grey ramps at the
+    house neutrals.
+  - `styles/fonts.css` — Pretendard Variable, dynamic subset.
+- Absorbs `@iyulab/enterprise/styles/preset.css`: the type scale, radius and elevation values now
+  live here with the rest of the house values (enterprise drops its copy in its next minor).
+- `npm test` — token contract: every light colour has a dark value (the house layer would
+  otherwise leak a light value into dark mode) and the promised contrast pairs hold in both modes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iyulab
+
+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,131 @@
+# House Style
+
+The iyulab house theme for `@iyulab/components`, `@iyulab/modern-app` and `@iyulab/flex-table`,
+and the guide that documents it.
+
+- **The theme** (`@iyulab/house-style` on npm) is CSS only: house token values, component
+  recipes, line-of-business layout patterns and a Tailwind CSS v4 preset. One import turns the
+  neutral component defaults into a finished, quiet, dense business UI.
+- **The guide** (the website below) shows every value read live from the theme it loads, so it
+  cannot drift from the files an application imports.
+
+## Use the theme
+
+```bash
+npm install @iyulab/house-style
+```
+
+```ts
+import '@iyulab/house-style';   // fonts + tokens + component recipes + layout patterns
+```
+
+**A Tailwind CSS v4 app** imports the Tailwind entry instead, from its Tailwind stylesheet — not
+`@iyulab/house-style` from JS:
+
+```css
+@import 'tailwindcss';
+@import '@iyulab/house-style/styles/tailwind.css';           /* theme + role utilities */
+@import '@iyulab/house-style/styles/tailwind-neutrals.css';  /* optional: gray-*/slate-* follow the theme */
+```
+
+Tailwind declares its own layers (`theme, base, components, utilities`) after the house layers,
+so its preflight would beat the theme; `tailwind.css` imports the theme into Tailwind's
+`components` layer — above preflight, below utilities and your own CSS.
+
+| File | What it holds |
+|---|---|
+| `styles/index.css` (package root) | everything below plus Pretendard — for apps without Tailwind |
+| `styles/theme.css` | the theme without fonts (bring your own face) |
+| `styles/tokens.css` | house values for the `--u-*` token axes, light and dark; brand tokens `--hs-brand*` |
+| `styles/components.css` | sizes and finish for `u-button`, `u-card`, `u-drawer`, `flex-table`, the app shell |
+| `styles/patterns.css` | `hs-*` layout patterns — page head, saved views, filter bar, stat strip, table card, callout, form sections, side-sheet footer |
+| `styles/tailwind.css` | the Tailwind v4 entry: fonts + theme (in Tailwind's `components` layer) + role utilities — `bg-canvas`, `text-ink-weak`, `border-line`, `bg-warning-soft`, `rounded-card` … |
+| `styles/tailwind-neutrals.css` | optional: Tailwind's grey ramps (`gray`, `slate`, `zinc`, `neutral`, `stone`) follow the house neutrals |
+| `styles/fonts.css` | Pretendard Variable (dynamic subset) |
+
+### Cascade layers — your CSS always wins
+
+```
+@layer iyu.base, iyu.house;
+  iyu.base    @iyulab/components built-in defaults
+  iyu.house   this theme
+  (unlayered) your application
+```
+
+Requires `@iyulab/components` 2.0 or later (the release that put its defaults in `iyu.base`).
+Because the application is unlayered, a plain `:root { … }` rule overrides the theme — no
+specificity tricks, no load-order rules. Scope a mode-specific value with `:root[theme="dark"]`.
+
+### Brand it
+
+The house is neutral on purpose. An application sets its identity colour with three tokens and
+keeps it out of buttons and warnings (a red brand next to a red "danger" reads as one colour):
+
+```css
+:root {
+  --hs-brand: #c8161d;        /* logo mark */
+  --hs-brand-soft: #fcebec;   /* current navigation item */
+  --hs-brand-ink: #a3121a;    /* its text */
+}
+:root[theme="dark"] {
+  --hs-brand-soft: #3a1a1c;
+  --hs-brand-ink: #ff9a9e;
+}
+```
+
+Everything else — warm-grey neutrals, the ink primary action, blue for links and focus, status
+tints, the 22/18/15/14/13/12/11 type ladder, 28/32/40 controls, 40px table rows — comes from the
+theme and can be overridden token by token.
+
+## The guide
+
+**Live**: https://iyulab.github.io/house-style/ — this is the guide. There is no
+separate docs site; the page above is the only place to read it.
+
+The live page is organized into sections:
+
+- **Visual identity & tokens** — type scale, colour roles, surfaces and ink, chart colours, radius, elevation
+- **Layout & viewport** — the responsive sidebar shell, nav/routes, breakpoints
+- **Component depth** — surfaces and controls at the standard radius and elevation
+- **Data patterns** — how tabular/record data is presented
+- **Feedback & motion** — alerts, progress, and waiting states
+- **User flows** — CRUD, wizard, and bulk-action patterns
+- **Voice, tone & accessibility** — focus visibility and keyboard interaction
+
+## The reference app
+
+The guide has a second half: a small but working line-of-business app, assembled only from
+these libraries, at **https://iyulab.github.io/house-style/app/** (sign in with `demo` / `demo`
+— the backend is mocked in the browser, there are no real accounts). It is reachable from the
+guide's sidebar under "Open the reference app".
+
+Where the guide shows each pattern on its own, the app shows them load-bearing: a sidebar shell,
+a list screen with filtering, selection and bulk actions, a master-detail order screen with an
+edit drawer, and a multi-step wizard. It is held to the guide rather than kept beside it — a
+check in this monorepo compares the two and reports any layout primitive one half uses and the
+other does not.
+
+Sections that say "Not yet decided" mean exactly that — no design decision has
+been made for that area yet, rather than the guide inventing one.
+
+## Local development
+
+From the `node-packages` monorepo root (never from inside this directory):
+
+```bash
+npm install
+npm run start -w @iyulab/house-style
+```
+
+The landing page's "Start here" path is checked end to end: a fresh `create-vite` project, the
+published packages, the page's own `index.html` / `main.ts` / recipe files, a production build,
+and a browser that must find table rows on `/`. The deploy workflow runs it before publishing the
+site; run it locally with (needs network and Playwright's Chromium):
+
+```bash
+npm run check:start-here -w @iyulab/house-style
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@iyulab/house-style",
+  "version": "0.1.0",
+  "description": "The iyulab house theme: a CSS-only theme for @iyulab components — tokens, component recipes, line-of-business layout patterns and a Tailwind CSS v4 preset — plus the guide site that documents it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iyulab/house-style.git"
+  },
+  "type": "module",
+  "style": "./styles/index.css",
+  "exports": {
+    ".": "./styles/index.css",
+    "./styles/*": "./styles/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "styles",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "preversion": "node -e \"if(require('fs').existsSync('../../scripts/preversion-check.mjs'))require('child_process').execFileSync('node',['../../scripts/preversion-check.mjs'],{stdio:'inherit'})\"",
+    "start": "vite",
+    "build": "npm run typecheck && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "check:start-here": "node scripts/check-start-here.mjs",
+    "test": "node --test \"tests/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "pretendard": "^1.3.9"
+  },
+  "peerDependencies": {
+    "@iyulab/components": "^2.0.0",
+    "@iyulab/flex-table": ">=0.41.0",
+    "@iyulab/modern-app": ">=0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "@iyulab/flex-table": {
+      "optional": true
+    },
+    "@iyulab/modern-app": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@iyulab/components": "^2.0.0",
+    "@iyulab/data-components": "^0.33.0",
+    "@iyulab/enterprise": "^0.22.0",
+    "@iyulab/modern-app": "^0.34.0",
+    "@iyulab/router": "^0.19.0",
+    "@iyulab/u-widgets": "^0.24.0",
+    "@lit/react": "^1.0.8",
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "echarts": "^6.1.0",
+    "lit": "^3.3.2",
+    "msw": "^3.0.0",
+    "playwright": "^1.62.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3"
+  },
+  "msw": {
+    "workerDirectory": [
+      "public"
+    ]
+  }
+}

package/styles/components.css

@@ -0,0 +1,125 @@
+/*
+ * @iyulab/house-style — component recipes
+ * ==========================================================================
+ * Element-level house defaults for `@iyulab/*` components, written only against their public
+ * surface: component custom properties (`--btn-*`, `--ft-*`, `--card-*`), `::part()` and the host.
+ * Nothing here changes what an attribute means — an `appearance="solid"` button stays solid; the
+ * house only sets size, density and finish.
+ *
+ * Everything sits in `@layer iyu.house`, so an application rule always wins. Rules aimed at a
+ * host beat the component's own `:host` styles (outer context wins over shadow context).
+ * ========================================================================== */
+
+@layer iyu.base, iyu.house;
+
+@layer iyu.house {
+
+/* ── Body ──────────────────────────────────────────────────────────────── */
+:root {
+  font-family: var(--u-font-base);
+  font-variant-numeric: tabular-nums;   /* amounts, counts, dates line up everywhere */
+  color: var(--u-txt-color);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* ── Button — 28 / 32 / 40, medium weight ─────────────────────────────── *
+ * Height follows the components' own formula (1.5em line + 2 × padding + 2px border), so
+ * these are padding values, not fixed heights: text and icon-only buttons stay equal.     */
+u-button:not([size]),
+u-button[size='md'] {
+  font-size: 13px;
+  --btn-padding-block: 5.25px;   /* 19.5 + 10.5 + 2 = 32 */
+  --btn-padding-inline: 12px;
+}
+u-button[size='sm'] {
+  --btn-padding-block: 4px;      /* 12px → 18 + 8 + 2 = 28 */
+  --btn-padding-inline: 8px;
+}
+u-button[size='lg'] {
+  font-size: 14px;
+  --btn-padding-block: 8.5px;    /* 21 + 17 + 2 = 40 */
+  --btn-padding-inline: 16px;
+}
+u-button[appearance='link'] {
+  --btn-padding-inline: 0;
+}
+
+/* ── Text fields — the same three heights as buttons: 28 / 32 / 40.
+ *    (Components 2.0 renders fields at 14px by default, so a field no longer grows with the
+ *    surrounding text; the house sets the box padding per size.) ── */
+:is(u-input, u-select, u-textarea, u-date-picker, u-date-range-picker)[size='sm'] {
+  --u-field-padding-block: 4px;     /* 12px → 18 + 8 + 2 = 28 */
+}
+:is(u-input, u-select, u-textarea, u-date-picker, u-date-range-picker)[size='lg'] {
+  font-size: 14px;
+  --u-field-padding-block: 8.5px;   /* 21 + 17 + 2 = 40 */
+}
+
+/* ── Tag — 22px labels (12px text · 1px block padding · hairline) to sit inside 40px rows.
+ *    A status label is the default `soft` appearance (tint, no outline) with `dot`. ── */
+u-tag {
+  --tag-padding-block: 1px;
+  --tag-padding-inline: 8px;
+  --tag-gap: 5px;
+}
+
+/* ── Card — flat surface, hairline border; shadow is for things that float ── */
+u-card {
+  --card-border-color: var(--u-border-color);
+}
+
+/* ── Drawer — the side sheet. Header and footer separated by a hairline,
+ *    body scrollbar always visible so long forms show there is more below. ── */
+u-drawer::part(header) {
+  border-bottom: 1px solid var(--u-border-color);
+}
+u-drawer::part(body) {
+  scrollbar-gutter: stable;
+  scrollbar-width: thin;
+  scrollbar-color: var(--u-border-color-strong) transparent;
+}
+
+/* ── Data table (`@iyulab/flex-table`) — 40px rows, 13px cells, quiet header,
+ *    no zebra (hover and selection carry the row), tabular figures. ──────── */
+flex-table {
+  --ft-font-family: var(--u-font-base);
+  --ft-font-size: 13px;
+  --ft-row-height: var(--hs-row);
+  --ft-cell-padding-inline: 12px;
+  --ft-header-font-size: 12px;
+  --ft-header-font-weight: 500;
+  --ft-header-text-color: var(--u-txt-color-weak);
+  --ft-header-bg: var(--u-bg-color-raised);
+  --ft-row-odd-bg: var(--u-bg-color);
+  --ft-row-odd-hover-bg: var(--u-bg-color-hover);
+  --ft-border-color: var(--u-border-color);
+  --ft-selection-bg: var(--u-primary-bg-color);
+}
+flex-table.hs-compact,
+.hs-compact flex-table {
+  --ft-row-height: var(--hs-row-compact);
+}
+
+/* ── Page header (`@iyulab/modern-app`) — eyebrow · 22px title · one-line description ── */
+u-page-header::part(eyebrow) {
+  font-size: var(--u-text-label-size);
+  color: var(--u-txt-color-weak);
+}
+u-page-header::part(subtitle) {
+  font-size: var(--u-text-label-size);
+  color: var(--u-txt-color-weak);
+}
+
+/* ── Sidebar layout — the sidebar is a surface separated from the canvas by a hairline.
+ *    (The page already sits on `--u-canvas-bg-color`; padding is `--app-main-padding`.) ── */
+u-sidebar-layout::part(sidebar) {
+  border-inline-end: 1px solid var(--u-border-color);
+}
+@media print {
+  u-sidebar-layout::part(main) {
+    background: none;
+    padding: 0;
+  }
+}
+
+} /* @layer iyu.house */

package/styles/fonts.css

@@ -0,0 +1,11 @@
+/*
+ * @iyulab/house-style — fonts
+ * ==========================================================================
+ * Pretendard Variable, dynamic subset: the browser downloads only the glyph ranges a page
+ * uses. `--u-font-base` (tokens.css) lists it first and falls back to the platform's Korean
+ * and system fonts when it is not loaded.
+ *
+ * Kept separate from the theme so an application that already ships Pretendard (or another
+ * face) can skip it: import `styles/theme.css` instead of `styles/index.css`.
+ * ========================================================================== */
+@import 'pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css';

package/styles/index.css

@@ -0,0 +1,11 @@
+/*
+ * @iyulab/house-style — everything: fonts + tokens + component recipes + patterns
+ *
+ *   import '@iyulab/house-style';            // same file, via the package "style"/"." entry
+ *   import '@iyulab/house-style/styles/index.css';
+ *
+ * 🔴A Tailwind CSS v4 app imports `styles/tailwind.css` from its Tailwind entry INSTEAD of this
+ * file — Tailwind's preflight layer would otherwise beat the theme (see tailwind.css).
+ */
+@import './fonts.css';
+@import './theme.css';