{"id":49769020,"url":"https://github.com/theory-cloud/theory-cloud-design","last_synced_at":"2026-05-27T02:00:53.207Z","repository":{"id":352019141,"uuid":"1212934748","full_name":"theory-cloud/theory-cloud-design","owner":"theory-cloud","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-18T14:37:29.000Z","size":4350,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T16:33:54.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theory-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T22:02:12.000Z","updated_at":"2026-05-18T14:41:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/theory-cloud/theory-cloud-design","commit_stats":null,"previous_names":["theory-cloud/theory-cloud-design"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/theory-cloud/theory-cloud-design","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2Ftheory-cloud-design","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2Ftheory-cloud-design/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2Ftheory-cloud-design/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2Ftheory-cloud-design/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theory-cloud","download_url":"https://codeload.github.com/theory-cloud/theory-cloud-design/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theory-cloud%2Ftheory-cloud-design/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33546836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-11T11:53:05.302Z","updated_at":"2026-05-27T02:00:53.198Z","avatar_url":"https://github.com/theory-cloud.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# theory-cloud-design\n\nThe **Theory Cloud brand pack** — a publishable TypeScript package of\npopulated design tokens and canonical brand assets consumed by\nFaceTheory-based Theory Cloud applications.\n\nThis repo is the authoritative source for:\n\n- the Theory Cloud **token sets** — a dark-first base plus per-surface\n  variants for **Core**, **MCP**, and **Auth** — all shape-compatible\n  with `StitchTokenSet` from `@theory-cloud/facetheory`;\n- the **icon and asset set** — primary icon, monochrome variants,\n  favicon family, and social / OG card, generated from SVG masters;\n- the **master brand document** (`theory_cloud_branding_package.md`) —\n  the specification every token, asset, and rule in this repo\n  implements.\n\ntheory-cloud-design is **not open source** and **not published to npm**.\nIt ships as pinned GitHub release tarballs, consumed through\n`package.json` by each downstream Theory Cloud app.\n\n## Installation\n\n`@theory-cloud/design` peer-depends on `@theory-cloud/facetheory` for\nthe `StitchTokenSet` type. Both packages are distributed as pinned\nGitHub-release tarballs — **neither is published to npm** — so peer\nresolution cannot fall back to the public registry. Install both\ntarballs in the same `npm install` invocation so npm can match the\ninstalled FaceTheory version against the peer range:\n\n```bash\nexport THEORY_CLOUD_FACETHEORY_VERSION=3.4.1\nexport THEORY_CLOUD_DESIGN_VERSION=2.1.6 # x-release-please-version\n\nnpm install --save-exact \\\n  \"https://github.com/theory-cloud/FaceTheory/releases/download/v${THEORY_CLOUD_FACETHEORY_VERSION}/theory-cloud-facetheory-${THEORY_CLOUD_FACETHEORY_VERSION}.tgz\" \\\n  \"https://github.com/theory-cloud/theory-cloud-design/releases/download/v${THEORY_CLOUD_DESIGN_VERSION}/theory-cloud-design-${THEORY_CLOUD_DESIGN_VERSION}.tgz\"\n```\n\nRunning `npm install` on the design tarball alone will fail with\n`E404 @theory-cloud/facetheory` because npm tries to resolve the peer\nfrom the registry; pass both tarball URLs (or install FaceTheory\nfirst) to avoid the miss.\n\nThe design pack is validated against the FaceTheory version pinned\nabove; consumers should bump both tarballs together when they move\nto a newer FaceTheory release.\n\n## Usage\n\n```ts\nimport { theoryCloudCoreTokens } from \"@theory-cloud/design/tokens/core\";\nimport { theoryCloudMcpTokens  } from \"@theory-cloud/design/tokens/mcp\";\nimport { theoryCloudAuthTokens } from \"@theory-cloud/design/tokens/auth\";\nimport { iconPath, ogCardPngPath } from \"@theory-cloud/design/assets\";\n```\n\nEvery surface composes over a shared base, so drift between surfaces\nstays narrow by construction — see §29.E of the brand document.\n\n## Surfaces\n\n| Surface | Domain           | Accent emphasis                                        |\n| ------- | ---------------- | ------------------------------------------------------ |\n| Core    | `theorycloud.ai` | Balanced Core Blue; stable, authoritative              |\n| MCP     | `theorymcp.ai`   | Slightly stronger Violet Signal; active, agentic       |\n| Auth    | `autheory.app`   | Restrained accent, neutral surface tint; trust-forward |\n\nThe three surfaces always carry the **Theory Cloud [Surface]** header\npattern (§30.C). Consumer apps consume this pack through\nFaceTheory's `BrandHeader` primitive; the surface chip sits beside the\nTheory Cloud wordmark, never replaces it.\n\n## Layout\n\n```\ntheory-cloud-design/\n├── assets/                       canonical SVG masters + generated rasters\n│   ├── icon.svg                  primary full-color icon\n│   ├── icon-mono-light.svg       Ice White monochrome (for dark surfaces)\n│   ├── icon-mono-dark.svg        Graphite monochrome (for light surfaces)\n│   ├── favicon/                  PNG favicon set (16/32/48/192/512)\n│   ├── favicon.ico               multi-resolution ICO bundle\n│   ├── og-card.svg               social / OG card master\n│   └── og-card.png               social / OG card (1200×630)\n├── scripts/\n│   ├── build-assets.py           regenerates raster derivatives from SVG\n│   └── build-release-assets.sh   packages the release tarball\n├── ts/\n│   ├── package.json              @theory-cloud/design — published shape\n│   ├── tsconfig.json             ESM + declaration output\n│   ├── src/\n│   │   ├── index.ts              top-level re-exports\n│   │   ├── assets.ts             typed asset path constants\n│   │   └── tokens/\n│   │       ├── base.ts           shared Theory Cloud StitchTokenSet\n│   │       ├── core.ts           Core variant\n│   │       ├── mcp.ts            MCP variant\n│   │       ├── auth.ts           Auth variant\n│   │       └── index.ts\n│   └── scripts/copy-assets.mjs   stages assets/ into ts/dist/assets/\n├── theory_cloud_branding_package.md   master brand specification\n├── VERSION                       tracked by release-please\n├── release-please-config.json            stable release pipeline\n└── release-please-config.premain.json    prerelease pipeline\n```\n\n## Development\n\n```bash\nmake install     # npm ci inside ts/\nmake assets      # regenerate raster assets from SVG masters\nmake build       # tsc + stage assets into ts/dist/\nmake typecheck   # tsc --noEmit\nmake check       # typecheck (placeholder for lint + tests)\nmake pack        # npm pack --dry-run inside ts/\n```\n\nThe raster pipeline uses `cairosvg` and `Pillow` (Python). SVG stays\nthe authoring format; rasters are always regenerated from the vector\nmasters.\n\n## Release cadence\n\ntheory-cloud-design follows the same three-branch release flow as\nFaceTheory, AppTheory, and TableTheory:\n\n```\nfeature/*  ──merge──▶  staging  ──merge PR──▶  premain  ──merge PR──▶  main\n                          ▲                     │                      │\n                          └────── back-merge ───┴──────────────────────┘\n                                     after stable release\n```\n\n- **`staging`** — integration branch. All work lands here first.\n- **`premain`** — prerelease branch. Merges from `staging` trigger\n  `v0.Y.Z-rc.N` prerelease tags via release-please.\n- **`main`** — stable branch. Merges from `premain` trigger `v0.Y.Z`\n  stable tags via release-please.\n\nReleases are **immutable**. Published tags are never retagged; release\nassets are never overwritten. The pipeline refuses to re-upload to an\nalready-published release — any change requires a new version moving\nthrough the pipeline.\n\nConventional Commits drive the version bump. In this repo every\nmerged change is intended to publish, so the release-please changelog\nconfiguration keeps every standard Conventional Commit type visible:\n\n- `feat:` → minor\n- `fix:`, `docs:`, `chore:`, `refactor:`, `style:`, `test:`, `build:`, `ci:`, `perf:`, `revert:` → patch unless a higher-priority commit is present\n- `feat!:` / `fix!:` / `BREAKING CHANGE:` → major (pre-1.0 per semver convention)\n\nRelease-please generated release commits are the exception: they update\nversion files, tags, and release notes for the version already being cut;\nthey are not a separate product change that needs a second release.\n\nEach release uploads one asset:\n\n```\ntheory-cloud-design-${VERSION}.tgz\n```\n\nreachable at\n\n```\nhttps://github.com/theory-cloud/theory-cloud-design/releases/download/v${VERSION}/theory-cloud-design-${VERSION}.tgz\n```\n\n## Ownership\n\nThis repo is stewarded as the Theory Cloud brand pack. Consumers\n— FaceTheory, autheory, theory-mcp-server — pin release tarballs and\nreskin against this package; they do not edit it. Changes that ripple\ndownstream are coordinated through the\n`Theory Cloud Design System — v1 Rollout` Linear project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheory-cloud%2Ftheory-cloud-design","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheory-cloud%2Ftheory-cloud-design","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheory-cloud%2Ftheory-cloud-design/lists"}