Skip to content

README.md

Latest commit

 

History

History
98 lines (77 loc) · 5.12 KB

README.md

File metadata and controls

98 lines (77 loc) · 5.12 KB
Raw

Documentation index

Everything you need to understand, integrate, extend, and ship <feature-cards>. Start at the README for the elevator pitch; use this page as the map.

By role

You are… Start here Then read
Integrator (drop into a CMS page) INSTALL.md Cookbooks, Schema reference, FAQ
Designer / themer README § Theming Demo themes guide, ACCESSIBILITY
Contributor CONTRIBUTING AGENTS, Testing guide, Branching
Maintainer / releaser Release playbook DEPENDENCY-UPGRADES, SECURITY
Architect / reviewer ARCHITECTURE ADRs, Diagrams
AI agent AGENTS .cursor/rules/ (source of truth for conventions)

Core reference

Document What it covers
INSTALL.md npm & CDN install — usage patterns, exports, licence, smoke test
SCHEMA.md Canonical Card / FeatureCardsData JSON — every field, validation rule, example payloads
FAQ.md Common questions: frameworks, SSR, SEO, bundle size, licensing
TROUBLESHOOTING.md Symptom → cause → fix for integration and dev issues
TESTING.md Full test matrix: unit, fuzz, contracts, a11y, e2e, visual, browser bench
DEMO.md Live demo page: themes, motion, schema playground, mock CMS
RELEASE.md Version bumps, changelog, tags, npm publish, SRI, CEM checklist
NPM.md npm doc index (links INSTALL + NPM-PUBLISH)
NPM-PUBLISH.md Maintainer publish playbook (@techystuff org, 2FA, tarball)
Rule 50-npm-package (.cursor/rules/) npm identity & release consistency invariants

Architecture & decisions

Document What it covers
ARCHITECTURE.md Narrative: why Web Components, Shadow DOM, schema, containers
diagrams/architecture.md Mermaid diagrams: data flow, deploy topology, theme layers
adr/0001 Custom Element over framework
adr/0002 Shadow DOM encapsulation
adr/0003 Zod schema + adapter layer
adr/0004 AGPL + canary provenance
adr/0005 Container-query responsiveness
adr/0006 Demo page themes & motion (not shipped in npm API)

CMS cookbooks

Step-by-step integration guides with copy-paste snippets:

  • Cookbook index — choose your integration pattern
  • WordPress — classic/block themes, REST, imperative mount
  • Contentful — content model, Delivery API, static JSON webhook pattern
  • Sanity — GROQ, HTTP API, Studio preview workflow

Operations

Document What it covers
BRANCHING.md master vs feature branches, PR previews, branch hygiene
DEPENDENCY-UPGRADES.md Deferred major bumps and security audit notes
openapi/cms-api.json OpenAPI schema for the mock CMS Worker
loc-report.md Generated LOC snapshot (npm run loc:report)

Policy & quality

Document What it covers
ACCESSIBILITY.md WCAG mapping, keyboard, screen readers, known limits
SECURITY.md Vulnerability reporting, XSS surface, canary verification
LEGAL.md Copyright enforcement, DMCA, evidence chain, commercial licensing
TRADEMARK.md Name and logo usage policy
TERMS_OF_USE.md Live demo site terms
CHANGELOG.md Version history (Keep a Changelog)
CONTRIBUTING.md PR checklist, commit style, ground rules

Generated artefacts (not hand-edited)

Path Generate with
docs/api/ npm run docs:api (TypeDoc)
custom-elements.json npm run cem / npm run build:lib
.vscode/html-custom-data.json derived from CEM

CI uploads TypeDoc and coverage as workflow artifacts; they are not hosted as a public site yet.

Live endpoints

Service URL
Demo (Pages) 501fun.humza-butt.space
Mock CMS cms.501fun.humza-butt.space/api/cards
OpenAPI cms.501fun.humza-butt.space/openapi.json
npm package @techystuff/feature-cards

Package: @techystuff/feature-cards@1.1.1 · Licence: AGPL-3.0-only