Skip to content

docs(readme): polish for visitor-facing clarity #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xiaoland merged 1 commit into from
Oct 17, 2026
+172 −143
Merged

docs(readme): polish for visitor-facing clarity #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
# Contributing

The organization-wide Git and pull-request policy lives in
[InKCre Git and GitHub Governance](https://github.com/InKCre/.github/blob/main/GOVERNANCE.md).
This guide covers the `ui`-specific development, delivery, and joint-development workflows
required by that policy.

## Setup

```bash
git submodule update --init --recursive docs/_shared
pnpm install --frozen-lockfile
pnpm generate
```

Install once at the repository root. Do not install from individual package directories;
the root `pnpm-lock.yaml` is the only dependency lock. Dependency lifecycle scripts are
denied by default; the reviewed allowlist lives in `pnpm-workspace.yaml`.

Run all project commands through pnpm. The root `packageManager` field selects pnpm, and
`devEngines.runtime` resolves the exact Node.js runtime into the lockfile.

## Daily commands

```bash
pnpm dev # Run the web package development server
pnpm story:dev # Run the interactive component catalog
pnpm type-check # Check root scripts and Vue source
pnpm generate # Rebuild tokens, package metadata, and Agent Skills
pnpm build # Build the publishable package
pnpm story # Build the component catalog
pnpm check # Run the complete local/CI baseline
```

`pnpm generate` produces derived files from the public component manifest: the runtime
registry, global component types, package version, Story coverage, and generated Agent
Skills. Token JSON changes always require `pnpm generate` before consumption.

## Testing

This repository has no automated unit/component test suite and no `pnpm test` command.
Run targeted checks for daily changes; use `pnpm check` as the complete local/CI baseline.
For interaction or visual behavior changes, also review the affected Story or real
consuming page — build and coverage checks do not prove those behaviors correct.
Check selection follows the [organization verification policy](https://github.com/InKCre/.github/blob/main/TESTING.md).

## Token pipeline

`tokens/inkcre.tokens.json` is the Token specification source. Figma proposes value
updates against existing paths; the generator owns generated outputs.
See [Token Guide](tokens/tokens.md) for the input format and maintenance entry, and
[Token Build Notes](scripts/build-tokens.md) for generation commands and outputs.

`scripts/build-tokens.ts` uses [Style Dictionary](https://www.npmjs.com/package/style-dictionary)
to produce:

- `packages/web/styles/tokens/_ref.scss`
- `packages/web/styles/tokens/_sys.scss`
- `packages/web/styles/tokens/_comp.scss`
- `packages/web/styles/uno/preset-ink.ts`

## Histoire delivery

The showcase build uses the lockfile-pinned Vue and Histoire highlight implementations,
bundled by Vite. Do not swap Vue for a CDN production build or stub Shiki with an empty
object; Histoire's state sync and source panel depend on these libraries' actual runtime
contracts.

`UI checks` validates Histoire as part of the repository contract. After a successful
same-repository run, the trusted Preview workflow checks out that exact pull-request head,
builds Histoire itself, and publishes to the stable `pr-N.design-dd4.pages.dev` preview
alias. Closing the pull request replaces the alias with a noindex marker; Cloudflare
retains older immutable deployment URLs as platform history.

A protected `main` push builds Histoire again as a focused release, transfers the exact
same-run artifact to the deployment job, and publishes it to
[design.inkcre.dev](https://design.inkcre.dev). Package publication and Histoire delivery
are independent outputs of `main`: one may be retried without republishing the other.
`wrangler.toml` owns the Pages project name, output directory, and compatibility date.
Delivery jobs run through GitHub environments; the Cloudflare credential remains a
selected organization Actions secret.

## Joint development with impl-ts

The consuming Vite/Vitest/TypeScript pipeline owns source consumption. Keep this
workspace installed and generated, then opt in from a sibling `impl-ts` checkout:

```bash
pnpm install --frozen-lockfile
pnpm generate
pnpm --dir ../impl-ts dev:ui --ui-source ../ui/packages/web
```

The command validates this package root and maps only its public specifiers for the
current development process. It does not use `pnpm link`, persist an absolute path, or
modify either manifest or lockfile. Token JSON changes still require `pnpm generate`.

Run the consumer source-graph check with
`pnpm --dir ../impl-ts type-check:ui --ui-source ../ui/packages/web`.
Normal client development, builds, checks, and CI remain pinned to the published
registry artifact. The consumer's
[`docs/40-deployment/development-runtime.md`](https://github.com/InKCre/impl-ts/blob/main/docs/40-deployment/development-runtime.md#joint-development-lanes)
owns the full startup, remotes, cleanup, troubleshooting, and release-fidelity contract.

## GitHub Packages authentication

The committed `.npmrc` routes only the `@inkcre` scope to GitHub Packages. It never
stores or expands a credential. Local credentials belong to the trusted user
configuration.

For interactive one-time setup, create a classic GitHub personal access token with
`read:packages`, then let npm write it to your user-level configuration:

```bash
npm login --scope=@inkcre --auth-type=legacy --registry=https://npm.pkg.github.com
```

Use your GitHub username, the token as the password, and your public email when
prompted. Alternatively, a credential manager may inject `NODE_AUTH_TOKEN` into the
current process if your user-level `~/.npmrc` contains:

```ini
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
```

Do not add that credential line to the repository `.npmrc`. Verify access with the
package manager itself:

```bash
pnpm view @inkcre/ui-web version
pnpm install --frozen-lockfile
```

Treat `401` or `403` as an expired token, missing `read:packages`, or missing package
access. A `404` can also mean that the package name or repository access is wrong.
Re-run the native login flow after correcting the underlying GitHub permission; this
repository intentionally has no separate auth doctor.

## Shared product docs

Shared InKCre product truth and cross-unit contracts are mounted read-only at
`docs/_shared` from [`InKCre/docs`](https://github.com/InKCre/docs). Initialize the
pinned reference after cloning:

```bash
git submodule update --init --recursive docs/_shared
```

Do not edit the mounted files from this repository. The repo-root
`.agents/skills/edit-svc-shared-docs` wrapper points coding agents to the canonical
Hub-first edit and isolated ref-bump workflow.
164 changes: 21 additions & 143 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,164 +1,42 @@
# InKCre UI

The InKCre design system and multi-platform UI workspace. The current web
renderer is published as `@inkcre/ui-web`.
The InKCre design system and the `@inkcre/ui-web` web renderer — design tokens, Vue components, and an interactive component catalog.

## Single Source of Truth
`ui` 是 InKCre 的设计系统仓库——维护 Token 源、Vue 组件和交互式组件目录，并通过 `@inkcre/ui-web` 发布给 Web 消费方。

[DESIGN.md](DESIGN.md) 提供设计总纲和按任务阅读的路径；设计立场、视觉语言、页面组合和判断依据由 `docs/design/` 分别维护。`tokens/inkcre.tokens.json` 是 Token 规范源，
Figma 仅提议已有路径的值更新；生成物通过生成器更新。
当前输入格式与维护入口见 [Token 指南](tokens/tokens.md)，生成命令与输出见
[Token 生成说明](scripts/build-tokens.md)。
## Repository shape

`scripts/build-tokens.ts` transforms the token source into:
- [`DESIGN.md`](DESIGN.md) — design principles and the per-task reading path
- `docs/design/` — design stance, visual language, page composition, and rationale
- `tokens/inkcre.tokens.json` — the Token specification source (Figma proposes value updates; the generator owns outputs)
- `packages/web/` — the `@inkcre/ui-web` Vue component package
- `scripts/build-tokens.ts` — the Token generator (Style Dictionary)

- `packages/web/styles/tokens/_ref.scss`
- `packages/web/styles/tokens/_sys.scss`
- `packages/web/styles/tokens/_comp.scss`
- `packages/web/styles/uno/preset-ink.ts`
## Quickstart

The generator uses
[Style Dictionary](https://www.npmjs.com/package/style-dictionary).

## Toolchain

The root manifest delegates both tools to pnpm:

- pnpm `11.17.0`
- Node.js runtime `22.22.3`

The root `packageManager` selects pnpm. Its `devEngines.runtime` entry makes
pnpm resolve the exact Node.js runtime into the lockfile and use it for project
scripts. Run project commands through pnpm rather than a separately managed
Node installation.

Install once at the repository root:
### Use the package

```bash
pnpm install --frozen-lockfile
pnpm add @inkcre/ui-web
```

Do not install from an individual package directory. The root
`pnpm-lock.yaml` is the only dependency lock.
Dependency lifecycle scripts are denied by default; the small reviewed
allowlist lives in `pnpm-workspace.yaml`.

## Shared product docs
See [`packages/web/README.md`](packages/web/README.md) for installation, public entries, and the Skills shipped with the package. Browse the live component catalog at [design.inkcre.dev](https://design.inkcre.dev).

Shared InKCre product truth and cross-unit contracts are mounted read-only at
`docs/_shared` from `InKCre/docs`. Initialize the pinned reference after cloning:
### Develop locally

```bash
git submodule update --init --recursive docs/_shared
```

Do not edit the mounted files from this repository. The repo-root
`.agents/skills/edit-svc-shared-docs` wrapper points coding Agents to the
canonical Hub-first edit and isolated ref-bump workflow.

## Development commands

```bash
pnpm dev # Run the web package development server
pnpm story:dev # Run the interactive component catalog
pnpm type-check # Check root scripts and Vue source
pnpm generate # Rebuild tokens, package metadata, and Agent Skills
pnpm build # Build the publishable package
pnpm story # Build the component catalog
pnpm check # Run the complete local/CI baseline
```

Generate derived files with `pnpm generate`. The public component manifest
drives the runtime registry, global component types, package version, Story
coverage, and generated Agent Skills.

本仓库目前没有自动化单元／组件测试套件，也没有 `pnpm test` 命令。
日常修改运行相关检查；完整本地／CI 基线使用 `pnpm check`。涉及交互或视觉行为时，
还需核对受影响的 Story 或真实消费页面；构建和覆盖检查不证明这些行为正确。
检查选择遵循 [组织验证政策](https://github.com/InKCre/.github/blob/main/TESTING.md)。

## 文档入口

- [设计决策指南](DESIGN.md)：消费者与维护者共享的默认选择、变化条件和扩展边界。
- [文档导航](docs/index.md)：维护与消费文档的入口。
- [仓库约定](AGENTS.md)与[Web 包约定](packages/web/AGENTS.md)：代码和生成物的维护责任。
- [包使用说明](packages/web/README.md)：安装、公开入口和随包 Skill。
- [UI 基础能力工作包](tasks/ui-foundations/packet.md)：当前任务的分组、状态和验证证据。

## Histoire delivery

展示构建使用 lockfile 中的 Vue 和 Histoire 高亮实现，由 Vite 打包到站点。不要把 Vue 单独替换成 CDN 生产版本，也不要用空对象模拟 Shiki；Histoire 的状态同步和源码面板依赖这些库的实际运行时契约。

`UI checks` validates Histoire as part of the repository contract. After a
successful same-repository run, the trusted Preview workflow checks out that
exact pull-request head, builds Histoire itself, and publishes it to the stable
`pr-N.design-dd4.pages.dev` preview alias. Closing the pull request replaces the
alias with a noindex marker; Cloudflare retains older immutable deployment URLs
as platform history.

A protected `main` push builds Histoire again as a focused release, transfers
the exact same-run artifact to the deployment job, and publishes it to
[design.inkcre.dev](https://design.inkcre.dev). Package publication and Histoire
delivery are independent outputs of `main`: one may be retried without
republishing the other. `wrangler.toml` owns the Pages project name, output
directory, and compatibility date. Delivery jobs run through GitHub environments;
the Cloudflare credential remains a selected organization Actions secret.

## Joint development with impl-ts

The consuming Vite/Vitest/TypeScript pipeline owns source consumption. Keep
this workspace installed and generated, then opt in from a sibling
`impl-ts` checkout:

```bash
pnpm install --frozen-lockfile
pnpm generate
pnpm --dir ../impl-ts dev:ui --ui-source ../ui/packages/web
pnpm story:dev
```

The command validates this package root and maps only its public specifiers for
the current development process. It does not use `pnpm link`, persist an
absolute path, or modify either manifest or lockfile. Token JSON changes still
require `pnpm generate`.
`pnpm check` is the required local/CI baseline. Setup, Token pipeline, Histoire delivery, joint development with `impl-ts`, and GitHub Packages authentication all live in [CONTRIBUTING.md](CONTRIBUTING.md).

Run the consumer source-graph check with
`pnpm --dir ../impl-ts type-check:ui --ui-source ../ui/packages/web`.
Normal client development, builds, checks, and CI remain pinned to the
published registry artifact. The consumer's
[`docs/40-deployment/development-runtime.md`](https://github.com/InKCre/impl-ts/blob/main/docs/40-deployment/development-runtime.md#joint-development-lanes)
owns the full startup, remotes, cleanup, troubleshooting, and release-fidelity
contract.

## GitHub Packages authentication

The committed `.npmrc` routes only the `@inkcre` scope to GitHub Packages. It
never stores or expands a credential. Local credentials belong to the trusted
user configuration.

For interactive one-time setup, create a classic GitHub personal access token
with `read:packages`, then let npm write it to your user-level configuration:

```bash
npm login --scope=@inkcre --auth-type=legacy --registry=https://npm.pkg.github.com
```

Use your GitHub username, the token as the password, and your public email when
prompted. Alternatively, a credential manager may inject `NODE_AUTH_TOKEN`
into the current process if your user-level `~/.npmrc` contains:

```ini
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
```

Do not add that credential line to the repository `.npmrc`. Verify access with
the package manager itself:

```bash
pnpm view @inkcre/ui-web version
pnpm install --frozen-lockfile
```
## Documentation

Treat `401` or `403` as an expired token, missing `read:packages`, or missing
package access. A `404` can also mean that the package name or repository
access is wrong. Re-run the native login flow after correcting the underlying
GitHub permission; this repository intentionally has no separate auth doctor.
- [Design principles and reading path](DESIGN.md)
- [Documentation index](docs/index.md)
- [Repository conventions](AGENTS.md) · [Web package conventions](packages/web/AGENTS.md)
- [Package usage](packages/web/README.md)
- Shared product truth Hub: [`InKCre/docs`](https://github.com/InKCre/docs) (mounted read-only at `docs/_shared/`)
Loading