Other: help / --help, version / --version. The MCP server stylegallery-mcp exposes search and read with the same JSON, plus the governed and compiler tools.

Worked homepage example

The StyleGallery homepage example was planned from a clean install of the published npm package. It demonstrates the Homepage recipe, selected layout patterns, agent-native CLI access, responsive behavior, and Chrome CDP verification in a standalone product-layer implementation.

The Toss-inspired homepage clone applies the same workflow to an observed external homepage: it maps the source into section jobs, composes existing Layout patterns, keeps brand styling in the example layer, and records desktop, mobile, keyboard, overflow, and reduced-motion checks.

The Scroll Story Lab adds runnable scroll-controlled product chapters, an image sequence with bounded decoding, native CSS scrubbing, and a static reading path. Start from Motion’s scroll-driven story for ownership and failure cases. The Scene Navigation example keeps the entire page fixed while wheel, keys, chapter links, and art-surface swipes select scenes; its separate contract covers input ownership, history, focus, and reading escape.

MCP server

Launch the packaged stdio server with:

npx --package stylegallery stylegallery-mcp

Example MCP client configuration:

{
  "mcpServers": {
    "stylegallery": {
      "command": "npx",
      "args": ["--yes", "--package", "stylegallery", "stylegallery-mcp"]
    }
  }
}

The main MCP server exposes governed read operations and compiler execution tools. Configure SG_COMPILER_ROOT in its environment to use the compiler. Execution tools declare file and network effects; the knowledge registry remains a read-only API. The frozen read-only server remains available as bun run sg:mcp:v1.

The main server also exposes search and read, the same operations and JSON as the CLI commands, so one server covers Markdown retrieval. The former Material v2 server (material-* tools) still runs as stylegallery-material-mcp in 0.1.12 with a rename notice on stderr.

한국어 빠른 시작

StyleGallery는 Node.js 22 이상에서 실행됩니다. 전역 설치 없이 바로 사용하려면 다음 명령을 실행하세요.

npx stylegallery discover --format json

자주 사용한다면 전역으로 설치할 수 있습니다.

npm install --global stylegallery
stylegallery discover --format json

설치만으로는 Claude Code, Codex, OmO가 StyleGallery를 쓰지 않습니다. 한 번 stylegallery setup을 실행하면 stylegallery-search 스킬을 각 에이전트의 사용자 스킬 폴더에 복사하고 stylegallery-mcp 서버를 등록합니다. --dry-run으로 바뀔 내용만 먼저 볼 수 있고, --agent claude|codex|omo|all, --only skill|mcp, --uninstall, --force를 지원합니다. 다시 실행해도 결과는 같고, 수정하는 설정 파일은 먼저 .bak-stylegallery-<시각>으로 백업하며, 같은 이름의 다른 설정은 --force 없이는 건드리지 않습니다. OmO는 Codex와 같은 ~/.agents/skills 스킬을 쓰고 MCP는 ~/.omo/agent/mcp.json(또는 $OMO_CODING_AGENT_DIR/mcp.json)에 등록합니다. 공유 스킬은 다른 에이전트가 아직 설치돼 있으면 --uninstall 때 남깁니다. 등록 확인은 claude mcp list 또는 codex mcp list로 하고, OmO는 다시 시작하면 반영됩니다.

stylegallery setup --dry-run
stylegallery setup

discover는 사용 가능한 인터페이스를 보여주고, resolve는 하나의 레코드를 조회하며, claims는 관련 주장과 근거를 분리해서 보여줍니다. context는 에이전트에 전달할 수 있는 제한된 컨텍스트 패키지를 만들고, ops는 지원하는 작업 목록을 반환합니다. 저장소를 직접 읽을 수 있는 에이전트는 AGENTS.md와 이 README의 작업 경로에서 시작해 로컬 Markdown을 따라가는 방식이 기본입니다. 경로가 불명확할 때만 stylegallery search "검색어" --paths-only --limit 5로 후보 경로를 좁히고, context는 파일에 직접 접근할 수 없거나 제한된 패키지를 전달해야 할 때 사용합니다. 모든 결과는 자동화에 바로 사용할 수 있는 JSON입니다.

전체 명령과 옵션은 위의 CLI reference에 정리되어 있습니다. 기본 흐름은 stylegallery search "sticky header" → stylegallery read --outline → stylegallery read --section 입니다.

CLI와 MCP의 상세 사용법은 Agent-Native StyleGallery 가이드를 참고하세요. 사람이 문서를 탐색하려면 아래의 도메인 표에서 목적에 맞는 진입점을 선택하면 됩니다.

For UI state ownership, asynchronous races, drafts, URL/history, and persistence, start with State Management in Design Engineering.

Domains

| Domain | Owns | Does not own | | --- | --- | --- | | Layout | Semantic spatial structure, flow, sizing, alignment, containment, scrolling, and composition. | Brand, typography, color, shadow, animation, and product decoration. | | Motion | Motion terminology, review procedure, and evidence-bounded practice guidance. | Universal timing/easing rules or permission to add motion to reusable Layout CSS. | | Design Engineering | Product-layer craft decisions and verification questions. | A second universal principle set or taste as evidence. | | Platform Guides | Bounded comparison with named platform conventions. | Affiliation, imitation, or authority over web and accessibility contracts. | | Design Terminology | Comparative design-term definitions, term families, and cross-system conflict cases for named systems. | StyleGallery's own vocabulary, motion terminology, visual token values, or authority over external vocabularies. | | Expression | Art direction for finished pages: direction briefs, named directions with values, visual technique recipes, and brand-study policy. | Layout mechanics, motion timing, governed tokens, or decorative values in reusable Layout pattern CSS. |

The canonical domain manifest and provenance policy are in StyleGallery Domains.

Practical Domain Workflows

| Task | Start | Apply and verify | | --- | --- | --- | | Design a transition | Motion Decision Tree | Brief, interaction recipes, and review | | Build a product interaction | Design Engineering Decision Tree | Component contract and worked examples | | Adapt a platform convention | Platform Adaptation Workflow | Apple, Android, Windows, and compatibility matrix | | Resolve a terminology conflict | Design Term Comparison Workflow | Directly sourced term cases and relation rules |

Layout 외 도메인도 선택 절차, 작성 양식, 적용 사례, 검증 경로를 제공합니다. 예제의 기대 결과는 실제 실행 증거와 구분하며, 공식 출처를 확인한 날짜와 적용 범위는 각 문서에 기록합니다. 문서 확충만으로 experimental 상태가 자동 승격되지는 않습니다.

Interaction Lab은 저장·검색·중첩 팝업·보상·입력 사례를 실행할 수 있는 브라우저 예제입니다. 검증 기록은 실제 Mac 브라우저에서 관찰한 결과와 모바일·네이티브 엔진 미검증 범위를 구분합니다.

Repository Entry Roles

Use each root hub for one primary job.

| Entry | Primary role | Use when | | --- | --- | --- | | README | Repository guide | You need the library purpose, policies, and task routes. | | OKF index | OKF bundle map | You need a compact knowledge-bundle table of contents. | | Layout Planning Guide | Planning workflow | You need to classify a screen before choosing patterns. | | Layout Pattern Catalog | Pattern lookup | You already know the spatial problem or pattern name. | | Governance, Lifecycle, And Docs-As-Code | Governance reference | You need the source of truth, lifecycle, generated-file, ownership, or stale-audit rule. | | StyleGallery Domains | Domain manifest | You need domain ownership, scope, lifecycle, page membership, or provenance. | | Consumer Reference | Shared infrastructure contract | You need to declare a consumer-owned record or explain why one is not applicable. | | Agent-Native StyleGallery | Machine interface guide | A person or agent needs to discover, resolve, retrieve, or inspect governed StyleGallery knowledge through CLI or MCP. | | Layout | Layout domain hub | You need reusable spatial patterns, recipes, or planning routes. | | Motion | Motion domain hub | You need motion terminology, review procedure, or practice evidence. | | Design Engineering | Design Engineering domain hub | You need product-level interface-craft decision guidance. | | Platform Guides | Platform Guides domain hub | You need a bounded platform comparison. | | Design Terminology | Design Terminology domain hub | You need to compare how named design systems define or classify design terms. | | Expression | Expression domain hub | You need a page to look and feel finished: type, color, texture, atmosphere, or a brand study. | | Showcase | Free-form work area | You are building a complete expressive page checked by outcome instead of Layout authoring rules. |

Task Routes

Each common task has one primary route. Use secondary links only after the primary route answers the first decision.

| Task | Primary route | Why | | --- | --- | --- | | choose a StyleGallery domain | StyleGallery Domains | It separates domain ownership before a reader applies domain-local guidance. | | browse reusable spatial guidance | Layout | It preserves the existing pattern, recipe, and planning routes. | | name or review interface motion | Motion | It routes to bounded terminology and review guidance. | | review product-level interface craft | Design Engineering | It separates practitioner heuristics from shared quality gates. | | compare adversarial consumer identities | Reference Profiles | It keeps non-default product values in related Design Engineering examples over one pinned Layout source. | | compare a named platform convention | Platform Guides | It requires platform and evidence boundaries before adaptation. | | compare how design systems define a term | Design Terminology | It separates external terminology comparison from StyleGallery's own controlled vocabulary. | | build a striking landing page in one shot | Showcase | It removes Layout authoring rules, supplies directions and techniques, and checks the result by outcome. | | turn raw content into a homepage or ordinary webpage | Webpage Generation Workflow | It starts with use case, content-to-layout fit, harmony, and handoff. | | plan a screen before the layout problem is obvious | Layout Planning Guide | It sequences task, content, scroll, recipe, and verification choices. | | choose a pattern when the name is unknown | Decision Tree | It routes from constraints to pattern categories. | | fill in requirements before selecting a pattern stack | Layout Brief Template | It captures content, constraints, and verification inputs. | | stabilize repository terminology | Controlled vocabulary | It defines canonical terms, aliases, deprecated terms, and scannability rules. | | compose a full screen from primitives | Layout Recipes | Recipes map screen models to pattern stacks. | | inspect which primitives a recipe depends on | Primitive To Recipe Matrix | It names essential, helper, and substitutable slots. | | look up a known layout primitive | Layout Pattern Catalog | It is the generated pattern lookup surface. | | browse pattern categories | Pattern Categories | It groups generated patterns by spatial family. | | check whether a layout or design claim is admissible | Quality Gates | It routes claims to gates and evidence boundaries. | | prove repository checks and evidence coverage | Executable Evidence Coverage | It maps validators, fixtures, CI commands, and their boundaries. | | declare consumer reference applicability | Consumer Reference | It provides the required handoff field without moving consumer values into Layout. | | use StyleGallery from an agent or automation | Agent-Native StyleGallery | It routes frozen v1 trust queries, material v2 discovery/search/get/context, extensions, lifecycle dispositions, and archive boundaries. Use SG Website Compilation for compiler commands in the main CLI and MCP. | | prove an existing consumer migration | Consumer Migration Readiness | It requires thirteen explicit behavior classifications, runtime proof, adoption mappings, and source-bound page evidence when applicable. | | change generated patterns, catalog, or governance policy | Governance, Lifecycle, And Docs-As-Code | It identifies source files, generated artifacts, validators, lifecycle state, and review ownership. | | run findability QA | Tree-Test Findability QA | It tests whether task routes are discoverable, not just linked. |

Link Policy

• Navigation links move a reader to the next decision point in the repository. Root hubs, indexes, parent links, and next-step links are navigation links.
• Citation links identify source lineage or evidence boundaries. They support a claim but should not be the only way to continue a task.
• Dependency links identify generated, validation, or composition relationships. They explain what must stay in sync, such as scripts/pattern-data.mjs, generated pattern files, catalog entries, and validator fixtures.

How To Use This Repository

• Start with StyleGallery Domains when the owning domain is not already clear.
• Use Layout, Motion, Design Engineering, Platform Guides, Design Terminology, or Expression as the domain-local entry point.
• Start with Layout Planning Guide when you are designing a screen before a layout problem is obvious.
• Use the Webpage Generation Workflow when raw content needs to become a homepage or ordinary webpage before a layout recipe is obvious.
• Use the Documentation Mode Taxonomy when adding or reviewing docs so each page has a clear primary reading mode.
• Use the Controlled vocabulary when a term affects routing, metadata, search, claim records, workflow handoff, or review decisions.
• Use the Decision Tree when you do not know the pattern name yet.
• Fill out the Layout Brief Template before choosing a pattern stack.
• Use Layout Recipes when you need screen-level composition.
• Use Layout Pattern Catalog when you already know the spatial problem.
• Use Quality Gates when a claim needs principle-backed evidence, visual QA boundaries, accessibility precedence, or design rationale.
• Use Consumer Reference when an implementation handoff must declare one repository-local JSON reference or a sentence explaining non-applicability.
• Use Agent-Native StyleGallery when a person, script, or agent needs deterministic JSON discovery, StableRef/VersionID resolution, bounded context, operation metadata, or read-only MCP access.
• Use Consumer Migration Readiness only for a migration that declares a consumer-local conformance record; ordinary handoffs keep the existing not_applicable path.
• Use Governance, Lifecycle, And Docs-As-Code before changing generated artifacts, validators, lifecycle state, or ownership policy.

Layout Domain Principles

Layout patterns solve one primary spatial problem with semantic structure, robust plain HTML/CSS, explicit constraints, named scroll ownership, and no decorative debt. The detailed principles live in the Layout domain contract.

CSS Authoring Policy

Reusable Layout CSS favors low specificity, intrinsic sizing, logical properties, and responsiveness at the correct container or viewport boundary. See the detailed CSS authoring policy.

Class Naming Policy

Layout class names describe stable spatial responsibilities and relationships rather than appearance or DOM depth. See the detailed class naming policy.

Value And Token Policy

Tokens represent stable shared design intent; browser and context mechanics remain explicit CSS values. See the detailed value and token policy.

Pattern Contract

Every pattern documents its primary problem, structure, constraints, scroll ownership, accessibility, fallbacks, composition, and failure boundaries. See the detailed pattern contract, and use the generated Pattern Categories as the category inventory.

Verification Matrix

Pattern verification covers the relevant viewport, container, content, direction, writing-mode, interaction, overflow, focus, and sticky/scroll cases. See the detailed verification matrix.

Releasing

The npm package is published from GitHub Actions through npm Trusted Publishing. The repository stores no npm token, and nothing is published from a local machine.

1. Open a pull request that bumps version in package.json, adds the log.md entry, and refreshes the search embeddings (bun run generate:search-embeddings, since log.md is embedded), the material registry, and the lifecycle hashes that the version change touches. Merge it after CI passes.
2. Create a GitHub Release from main whose tag is v plus the new version, for example v0.1.11.
3. Publishing the release runs .github/workflows/publish.yml. The workflow checks that the tag matches package.json, runs the governance, lifecycle, reference-artifact, material, and Registrar checks, and runs npm publish with a short-lived OIDC credential. npm attaches provenance automatically.

License

Source code is licensed under the MIT License (LICENSE). Documentation is licensed under Creative Commons Attribution 4.0 International (LICENSE-DOCS). Material adapted from external sources keeps its original rights; see NOTICE and the External Adaptation Contract.