Blocks installation
Copy a PyColors Block source directory into your app, keep the source under your ownership, and validate it with public UI imports.
Explore the Blocks catalog to choose an application shell, authentication panel, commerce surface, data table, account/workspace surface, empty state or other documented pattern before following the installation steps below.
Copy source, then own itLink to section
PyColors Blocks use a manual source-copy flow. When a Block is available, copy its canonical source directory into your application, then treat the copied code as your own product code.
Canonical documented Blocks
The category and naming contract is approved. The documented catalog includes
app-shells/responsive-sidebar,
auth/sign-in,
auth/sign-up,
auth/password-recovery,
data/data-table,
account/settings-panel,
commerce/pricing-plans,
commerce/billing-overview,
commerce/payment-method,
commerce/invoice-history,
feedback/empty-state-panel,
account/workspace-members,
account/workspace-invitations
and account/audit-log. Other merged
canonical source is surfaced through separately reviewed docs/catalog parity
issues before it becomes part of this public discovery contract.
There is no @pycolors/blocks package, proprietary PyColors CLI, or automatic
synchronization. Copying source does not change a package version and does not
require a Changeset.
The Registry pilot guide documents a separate base and
feedback-empty-state-panel workflow through the upstream shadcn CLI. Public
mirror installation still requires its separate availability check. The manual
flow on this page stays supported and is not replaced by the pilot.
Canonical source locationLink to section
The PyColors repository keeps canonical Block source at:
apps/marketing/content/blocks/<category-slug>/<block-slug>/Both path segments use lowercase kebab-case. <category-slug> must be one of
the approved slugs below, and each production Block owns one stable
<block-slug>.
Approved categoriesLink to section
Every Block has exactly one primary category. Tags may support secondary discovery without creating duplicate source or category aliases.
| Category | Slug | Source-owner issues |
|---|---|---|
| Application shells | app-shells | #94 |
| Authentication | auth | #95 |
| Commerce | commerce | #96 and #98 |
| Account & workspace | account | #97 and #99 |
| Data & records | data | #101 |
| Feedback & states | feedback | #100 |
Source, documentation navigation, and Registry metadata use the same
<category-slug>/<block-slug> identity. For example, data/data-table maps to
the documentation route /docs/blocks/data/data-table and, only after a
separate Registry approval, the Registry item data-data-table.
Free and Pro availability are separate metadata on this shared identity. They do not create different taxonomies or expose private source.
Documentation previews must import or render canonical Block source where practical. A preview is never an alternate implementation to copy from.
Source authority
@pycolors/ui and @pycolors/tokens remain the public primitive and token
authorities. Starter Free is product evidence and documentation previews are
examples, not alternate Block source. Registry artifacts distribute canonical
source only, while future Pro remains a separate authority under #36. The
approved first source sequence was #94, then #101, then #97; current
sequencing is coordinated by #35.
Install a BlockLink to section
Copy the complete source directoryLink to section
Copy the canonical <block-slug> directory into a location your app owns,
such as src/components/blocks/<block-slug>. Keep the Block's local files
together so its relative imports remain local to the copied source.
Use public PyColors UI importsLink to section
Install and configure @pycolors/ui in the consuming app by following the
UI installation guide. Block source must import
PyColors primitives from the public package entry point only when it needs
them.
import { Button, Card } from "@pycolors/ui";Do not use @pycolors/ui/src/*, @pycolors/ui/dist/*, internal app
aliases, or private @pycolors/* packages. React or Next imports are
appropriate only when the copied Block actually needs them.
Customize the copied codeLink to section
The copied code belongs to your application. Adapt it to your routes, content, styling, state, and product rules. PyColors does not automatically update or synchronize copied Block source.
Validate the resultLink to section
Run your application's lint, type-check, test, and build commands after copying or customizing a Block. Preserve accessible semantics, keyboard behavior, labels, and visible focus states while making changes.
Repository checksLink to section
PyColors maintainers validate this source-copy contract with:
pnpm check:blocks-contract
pnpm test:blocks-contract
pnpm --filter pycolors-marketing lint
pnpm --filter pycolors-marketing types:check
pnpm --filter pycolors-marketing buildThe structural check enforces the exact category allowlist and lowercase
kebab-case names, rejects empty placeholders, deep @pycolors/ui imports,
internal app or package imports, and package, registry, or CLI artifacts. It
validates the delivery contract without creating a sample production Block.
Updates are deliberateLink to section
Blocks are source copies, not a managed dependency. If a future canonical version changes, review it deliberately and bring across only the changes that fit your application. Your copy remains under your control until you choose to update it.
Copy directly from the documentationLink to section
Each available Block has a Copy source section with its complete canonical implementation. You do not need to locate monorepo files to inspect or copy that code:
- Copy Responsive sidebar.
- Copy Sign in.
- Copy Sign up.
- Copy Password recovery.
- Copy Data table.
- Copy Settings panel.
- Copy Pricing plans.
- Copy Billing overview.
- Copy Payment method.
- Copy Invoice history.
- Copy Empty state panel.
- Copy Workspace members.
- Copy Workspace invitations.
- Copy Audit log.
Open View and copy the complete source, then use the code block's copy button or select the code manually. Save it at the application-owned path shown above the source and continue with that guide's usage example. Configure the public UI package and tokens first; copied source does not install dependencies or styles for you.
The displayed file is included from canonical source when the documentation builds. Your application copy remains independent: review changes deliberately, validate your integration, and keep local customizations under version control. There is no new installer or automatic update service.
Need a whole application rather than one pattern? Compare Starters.