Platform Foundations is the shared foundation for PlainConcepts Platform apps. It keeps many independent apps consistent and easy for developers and AI agents to work in, without becoming a heavy in-house framework.

It covers the frontend (a shared theme, conventions, docs, and a themed showcase) and backend/.NET conventions (recommended skills and a reference architecture in ai/ARCHITECTURE.md).

It is not a component library, an app framework, or a design system to be maintained by hand.

ai/               ARCHITECTURE (incl. Stack) + DESIGN + AGENTS
skills/           reusable agent skills, including platform-onboard for brownfield migrations
apps/docs         Fumadocs (Next.js), docs + live themed component previews
packages/theme    @plainconceptsplatform/ui-theme, design tokens (CSS only)
packages/ui-components  @plainconceptsplatform/ui-components, shared React components (Plain logo, ...)

1. Prefer established open-source libraries over custom code.
2. Use shadcn/ui components directly; don't wrap them or build a proprietary library.
3. App-specific components live in the app. Share a component only after the same need appears in multiple apps.
4. The foundation owns the theme, conventions, docs, and showcase, nothing more.
5. Keep the scope small. Add a directory/package only when it has a clear job today.

Next.js (App Router) + React + TypeScript, shadcn/ui on Radix + Tailwind v4, themed by @plainconceptsplatform/ui-theme, icons from Lucide. DI via inversify-hooks (mandatory). Biome, Vitest + Playwright, pnpm. See ai/ARCHITECTURE.md.

pnpm install
pnpm dev          # run the docs/showcase site (Fumadocs)
pnpm lint         # Biome
pnpm test         # Vitest

The Platform theme and shared components are public npm packages. No registry configuration or token is required.

pnpm add @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-components tailwindcss

npx @plainconceptsplatform/ui-theme@latest init

This copies components.json, adds the theme import to your global stylesheet, and shows you how to wire the Outfit font in your root layout.

npx shadcn@latest add button card dialog ...

Full details in packages/theme/README.md.

Start with AGENTS.md. It points to the ai/ folder, which has conventions, architecture, design rules, and agent definitions. For an existing application that needs the full Platform stack, use platform-onboard. It assesses six domains in dependency order: agentic infrastructure, architecture docs, OpenSpec, frontend stack, loop automation, and .NET guardrails.

Reusable GitHub Agentic Workflow skills and copyable loops now live in PlainConceptsPlatform/agentic-workflows. Use its self-contained workflow-author and workflow-consumer skills when creating or adopting workflows.

• ai/ARCHITECTURE.md: reference architecture + stack (frontend and backend/.NET)
• ai/DESIGN.md: design tokens & UI rules
• skills/platform-onboard/SKILL.md: brownfield migration to Platform practices
• packages/theme/README.md: theme package setup and conventions
• packages/ui-components/README.md: shared components (Plain logo)
• apps/docs/README.md: docs/showcase site structure