{"id":51764467,"url":"https://github.com/iodigital-com/io-design-system","last_synced_at":"2026-07-19T17:34:20.123Z","repository":{"id":347967692,"uuid":"1193767357","full_name":"iodigital-com/io-design-system","owner":"iodigital-com","description":"Cross-framework design system built with Stencil Web Components and generated React, Vue, and Angular wrappers.","archived":false,"fork":false,"pushed_at":"2026-07-02T12:06:24.000Z","size":64778,"stargazers_count":0,"open_issues_count":13,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T12:19:30.594Z","etag":null,"topics":["angular","component-library","design-system","react","stenciljs","typescript","ui","vue","web-components"],"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/iodigital-com.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-03-27T15:03:23.000Z","updated_at":"2026-07-02T12:06:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iodigital-com/io-design-system","commit_stats":null,"previous_names":["iodigital-com/io-design-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iodigital-com/io-design-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iodigital-com%2Fio-design-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iodigital-com%2Fio-design-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iodigital-com%2Fio-design-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iodigital-com%2Fio-design-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iodigital-com","download_url":"https://codeload.github.com/iodigital-com/io-design-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iodigital-com%2Fio-design-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35661225,"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-07-19T02:00:06.923Z","response_time":112,"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":["angular","component-library","design-system","react","stenciljs","typescript","ui","vue","web-components"],"created_at":"2026-07-19T17:34:19.455Z","updated_at":"2026-07-19T17:34:20.116Z","avatar_url":"https://github.com/iodigital-com.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# io Design System\n\nio Design System is iO Digital's cross-framework component platform.\n\nIt provides one source of truth for UI components using Stencil Web Components, then generates framework wrappers for React, Vue, and Angular. This repository also contains a private storefront used for internal documentation, usage examples, API reference, and design-token visibility.\n\n## What This Repository Does\n\nThis repository is responsible for all of the following:\n\n1. Building and testing production web components under the io namespace.\n2. Generating wrapper libraries so product teams can consume the same components in React, Vue, and Angular.\n3. Maintaining a static Next.js documentation storefront for component docs and examples.\n4. Enforcing governance and quality gates for API surface, design tokens, bundle size, accessibility, and release hygiene.\n5. Publishing versioned packages under the iodigital-com scope to GitHub Packages.\n\n## Repository Contents\n\n| Package/Area | Name | Purpose | Published |\n|---|---|---|---|\n| Stencil core | @iodigital-com/components | Source of truth for all components and tokens | Yes |\n| React wrappers | @iodigital-com/components-react | Auto-generated React wrappers around core components | Yes |\n| Vue wrappers | @iodigital-com/components-vue | Auto-generated Vue wrappers around core components | Yes |\n| Angular wrappers | @iodigital-com/components-angular | Auto-generated Angular wrappers around core components | Yes |\n| Storefront | @iodigital-com/storefront | Internal docs/playground site | No (private) |\n| Scripts | scripts/ | Governance checks, sync helpers, automation | N/A |\n| Docs artifacts | docs/ | API snapshots, governance docs, token docs | N/A |\n\n## Component Catalog\n\nCurrent component set (55):\n\n- io-accordion\n- io-ai-tag\n- io-avatar\n- io-badge\n- io-banner\n- io-breadcrumb\n- io-button\n- io-button-group\n- io-button-pure\n- io-button-tile\n- io-carousel\n- io-checkbox\n- io-checkbox-group\n- io-divider\n- io-drawer\n- io-fieldset\n- io-flag\n- io-flyout\n- io-heading\n- io-icon\n- io-inline-notification\n- io-input\n- io-input-date\n- io-input-password\n- io-input-search\n- io-link\n- io-link-pure\n- io-link-tile\n- io-modal\n- io-multi-select\n- io-pagination\n- io-pin-code\n- io-popover\n- io-product-tile\n- io-progress\n- io-radio\n- io-radio-group\n- io-scroller\n- io-segmented-control\n- io-select\n- io-sheet\n- io-spinner\n- io-stepper\n- io-switch\n- io-table\n- io-tabs\n- io-tabs-bar\n- io-tag\n- io-tag-dismissible\n- io-text\n- io-text-list\n- io-textarea\n- io-toast\n- io-tooltip\n- io-wordmark\n\nComponent status (Stable or Beta) is governed in storefront status docs and rendered in the component pages.\n\n## Technology Stack\n\n- Stencil 4 for web component authoring.\n- TypeScript (strict patterns).\n- Vitest for unit and render coverage.\n- Next.js 16 for internal storefront docs.\n- npm workspaces for monorepo orchestration.\n- GitHub Packages for scoped distribution.\n- GitHub Actions for release automation.\n\n## Browser Support\n\nThis system targets modern evergreen browsers:\n\n- Chrome (latest)\n- Edge (latest)\n- Firefox (latest)\n- Safari (latest)\n\nInternet Explorer and other end-of-life browsers are out of scope.\n\n## Architecture and Source-of-Truth Rules\n\n1. All component behavior changes must happen in the Stencil core under io-components/src/components.\n2. React, Vue, and Angular wrappers are generated outputs and should not be hand-maintained.\n3. Design token ownership is in io-components/src/global/app.css.\n4. Storefront remains static-export compatible and consumes generated assets/types.\n5. Public events use canonical names only. io-prefixed public event names are blocked.\n\n## Quick Start (Local Development)\n\n### Prerequisites\n\n- Node 20 or newer.\n- npm (bundled with Node).\n\n### Install\n\n```bash\ngit clone https://github.com/iodigital-com/io-design-system.git\ncd io-design-system\nnpm ci\n```\n\n### Run local dev\n\n```bash\nnpm run dev\n```\n\nThis starts Stencil watch mode, the Next.js storefront, and the asset sync watcher concurrently. The storefront is available at http://localhost:3000.\n\n## Repository Structure\n\n```text\nio-design-system/\n  io-components/                  # Stencil core package (source of truth)\n    src/components/               # Component implementations\n    src/global/app.css            # Global design tokens\n    src/global/app.ts             # Global app behavior\n  io-components-react/            # Generated React wrappers\n  io-components-vue/              # Generated Vue wrappers\n  io-components-angular/          # Generated Angular wrappers\n  io-storefront/                  # Private Next.js docs site\n  docs/                           # API snapshots, token docs, governance docs\n  scripts/                        # Tooling, governance checks, sync automation\n  .github/workflows/              # CI and release workflows\n```\n\n## Command Reference\n\nAll commands below run from repository root unless stated otherwise.\n\n### Daily development commands\n\n```bash\nnpm run dev\nnpm run build\nnpm run test\nnpm run type-check\nnpm run lint\n```\n\n### Granular build commands\n\n```bash\nnpm run build:components\nnpm run build:wrapper:react\nnpm run build:wrapper:vue\nnpm run build:wrapper:angular\nnpm run build:wrappers\nnpm run build:storefront\nnpm run build:storefront:release\n```\n\n### Governance and safety checks\n\n```bash\nnpm run governance:check\nnpm run events:guard\nnpm run check:public-css-api\nnpm run api:check\nnpm run sync:stencil-assets:check\nnpm run token-naming:check\nnpm run token-runtime:check\nnpm run token-doc-coverage:check\nnpm run style-literals:check\nnpm run status-governance:check\nnpm run dark-mode-tokens:check\n```\n\n### Quality and compliance checks\n\n```bash\nnpm run size\nnpm run lighthouse:ci\nnpm run security:audit\nnpm run type-coverage\n```\n\n### Full gate command\n\n```bash\nnpm run build:quality-gates\n```\n\nThis runs the complete release-grade sequence:\n\n1. governance:check\n2. events:guard\n3. check:public-css-api\n4. lint\n5. build\n6. api:check\n7. sync:stencil-assets:check\n8. size\n9. test\n10. type-coverage\n11. type-check\n12. build:storefront\n13. lighthouse:ci\n14. security:audit\n\n### Token documentation pipeline\n\n```bash\nnpm run tokens:scrape\nnpm run tokens:scrape:resume\nnpm run tokens:merge\nnpm run tokens:html\nnpm run tokens:sync\n```\n\nThese generate and synchronize token docs artifacts under docs/.\n\n## How To Consume The Design System\n\nPackages are published to GitHub Packages under the iodigital-com scope.\n\n### Consumer .npmrc setup\n\nCreate project-level .npmrc:\n\n```ini\n@iodigital-com:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\nalways-auth=true\n```\n\n### Install packages\n\nInstall core only (vanilla web components):\n\n```bash\nnpm install @iodigital-com/components\n```\n\nInstall with framework wrappers:\n\n```bash\nnpm install @iodigital-com/components @iodigital-com/components-react\nnpm install @iodigital-com/components @iodigital-com/components-vue\nnpm install @iodigital-com/components @iodigital-com/components-angular\n```\n\n### Vanilla usage\n\n```ts\nimport { defineCustomElements } from '@iodigital-com/components/loader';\n\ndefineCustomElements();\n```\n\n```html\n\u003cio-button variant=\"solid\" color=\"blue\" size=\"md\"\u003eGet started\u003c/io-button\u003e\n```\n\n### React usage\n\n```tsx\nimport { IoButton } from '@iodigital-com/components-react';\n\nexport function Example() {\n  return \u003cIoButton variant=\"solid\" color=\"blue\" size=\"md\"\u003eGet started\u003c/IoButton\u003e;\n}\n```\n\n### Vue usage\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport { IoButton } from '@iodigital-com/components-vue';\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cIoButton variant=\"solid\" color=\"blue\" size=\"md\"\u003eGet started\u003c/IoButton\u003e\n\u003c/template\u003e\n```\n\n### Angular usage\n\n```ts\nimport { NgModule } from '@angular/core';\nimport { IoComponentsAngularModule } from '@iodigital-com/components-angular';\n\n@NgModule({\n  imports: [IoComponentsAngularModule],\n})\nexport class AppModule {}\n```\n\n### SSR and hydration guidance\n\nIn SSR apps (for example Next.js or Nuxt):\n\n1. Register custom elements in browser/client context only.\n2. Avoid direct DOM access during server render.\n3. Use hydration-safe defaults for controlled values.\n\nIf hydration mismatch appears, validate client-only registration before debugging component internals.\n\n## Theming and Tokens\n\nThe theming API is CSS custom properties under the io prefix.\n\n- Public API: --io-* custom properties.\n- Token source of truth: io-components/src/global/app.css.\n- Do not rely on internal class names or internal DOM shape as public contract.\n\n## Event Model\n\nPublic events follow canonical/native naming.\n\nExamples:\n\n- click\n- input\n- change\n- focus\n- blur\n- open\n- close\n- dismiss\n\nio-prefixed custom event names are intentionally not part of public API and are guarded by events:guard.\n\n## Accessibility Commitments\n\nThe system targets WCAG AA baseline for shipped components.\n\nEvery component change should preserve:\n\n1. Keyboard accessibility.\n2. Visible focus indicators.\n3. Correct semantic role/ARIA behavior.\n4. Contrast compliance.\n5. Reduced motion compatibility where relevant.\n\n## Opening an Issue\n\nUse the structured issue templates to route your request correctly:\n\n| What you need | Template to use |\n|---|---|\n| Something is broken (wrong behaviour, crash, visual regression, a11y failure) | **Bug Report** |\n| Propose a new component, prop, token, or storefront section | **Feature Request** |\n| Ask how to use a component or token correctly | **Implementation Question** |\n\nCreate a new issue at: [github.com/iodigital-com/io-design-system/issues/new/choose](https://github.com/iodigital-com/io-design-system/issues/new/choose)\n\nBlank / freeform issues are disabled — all issues must use a template so we can triage efficiently.\n\n### Choosing the right scope\n\n| Area | Scope label |\n|---|---|\n| Web component source code | `io-component` |\n| Documentation storefront | `io-storefront` |\n| Design tokens / CSS custom properties | `tokens` |\n| React / Vue / Angular wrapper package | `wrappers` |\n| Governance scripts or CI | `chore` |\n\n---\n\n## Contributing Workflow\n\nFor full details, see CONTRIBUTING.md. High-level path:\n\n1. Create a branch from main.\n2. Build and test locally.\n3. Make focused component/storefront changes.\n4. Regenerate generated outputs when API changes.\n5. Run full gates.\n6. Open PR with test evidence and migration notes if needed.\n\nSuggested start:\n\n```bash\ngit checkout -b feat/your-change\nnpm ci\nnpm run dev\n```\n\nBefore PR:\n\n```bash\nnpm run build:quality-gates\n```\n\n## Adding a New Component\n\nHigh-level checklist:\n\n1. Create io-components/src/components/io-name with implementation, styles, types, and tests.\n2. Add full storefront docs pages under io-storefront/src/app/components/io-name.\n3. Build core and sync storefront generated types/assets.\n4. Register new component in storefront sitemap.\n5. Re-run tests and full quality gates.\n\nGenerated files and wrappers must not be hand-maintained.\n\n## API Surface Governance and Breaking Changes\n\nThis repo tracks public API contracts using docs/api-surface.json.\n\n- Use npm run api:check to detect unapproved API breaks.\n- Use npm run api:snapshot to intentionally update baseline when breaking change is approved.\n\nSemVer policy:\n\n- MAJOR: complete visual overhaul of the design system (new brand palette, full token rename). Not for individual API changes.\n- MINOR: new components, new props, new defaults, removals with migration path.\n- PATCH: bug fixes, a11y fixes, visual tweaks, doc fixes.\n\nConventional commits are expected for clarity in release intent.\n\n## Release and Publishing\n\n### Registry\n\nAll publishable packages target:\n\n- https://npm.pkg.github.com\n- scope: @iodigital-com\n\n### Release workflow\n\nReleases are driven by Changesets. On merge to main, the release workflow opens a Release PR aggregating all pending changesets. When that PR merges, packages publish to npm with provenance attestation.\n\nTo add a changeset for your PR:\n\n```bash\nnpm run changeset:add\n```\n\nUse `@iodigital-com/components` as the package name (not `@io-digital/components`).\n\n### Publish preconditions\n\n1. Version in package.json matches release tag version for tag-based releases.\n2. Full quality-gate job passes.\n3. Target version does not already exist in registry.\n4. Publish environment approvals (if configured) are satisfied.\n\n### Local maintainer publish flow\n\nIf doing a local/manual publish:\n\n```bash\nnpm ci\nnpm run build:quality-gates\n\nnpm publish --workspace @iodigital-com/components --registry https://npm.pkg.github.com\nnpm publish --workspace @iodigital-com/components-react --registry https://npm.pkg.github.com\nnpm publish --workspace @iodigital-com/components-vue --registry https://npm.pkg.github.com\nnpm publish --workspace @iodigital-com/components-angular --registry https://npm.pkg.github.com\n```\n\nPublish core first, then wrappers.\n\n### Maintainer token setup\n\nExample user-level .npmrc:\n\n```ini\n@iodigital-com:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GH_PACKAGES_TOKEN}\nalways-auth=true\n```\n\nToken scopes:\n\n- read:packages\n- write:packages\n- repo when org policy requires repository-scoped access\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| 401 Unauthorized when install/publish | Missing or invalid token | Confirm token value and scopes, then retry |\n| 404 for @iodigital-com package | Registry scope mapping missing or package/version not published | Verify .npmrc mapping and run npm view against GitHub registry |\n| Wrapper install warnings | Core-wrapper version mismatch | Align versions and reinstall dependencies |\n| CI release skips publish | Version already exists | Bump version and rerun release |\n| Storefront type drift check fails | Generated files outdated | Run build:components and sync:stencil-assets |\n\nUseful checks:\n\n```bash\nnpm config get @iodigital-com:registry\nnpm view @iodigital-com/components versions --registry https://npm.pkg.github.com\nnpm ls @iodigital-com/components\n```\n\n## Security and Governance Notes\n\n1. Do not commit package tokens or credentials.\n2. Use runtime environment variables for npm auth.\n3. Keep release automation under review with least-privilege permissions.\n4. Run governance and audit scripts before publishing.\n\n## Additional Docs\n\n- CONTRIBUTING.md for implementation and PR rules.\n- AGENTS.md for architecture boundaries and agent guidance.\n- docs/agency-agents/README.md for AI workflow and governance context.\n- docs/component-stability-recommendations.md for stability posture.\n- docs/storefront-status-governance.md for status governance rubric.\n\nIf you are new to the repo, start with this README, then move to CONTRIBUTING.md before opening your first PR.\n\n## FAQ\n\n### Which package should I install first?\n\nAlways start with @iodigital-com/components. If you use a framework, add its wrapper package as well.\n\n### Is io-storefront published to npm?\n\nNo. io-storefront is the documentation/playground app and stays in-repo.\n\n### How do I validate my change before opening a PR?\n\nRun the full gate:\n\n```bash\nnpm run build:quality-gates\n```\n\n### Where should I add new design values?\n\nAdd new tokens in io-components/src/global/app.css first, then consume them in component styles via var(--io-*).\n\n### What is the quickest way to work on a component and docs together?\n\nRun npm run dev, implement in io-components/src/components, and verify behavior in the matching io-storefront/src/app/components pages.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiodigital-com%2Fio-design-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiodigital-com%2Fio-design-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiodigital-com%2Fio-design-system/lists"}