Installation

Cardspark requires React 18 or newer and is published as an ESM package. Its visual components are Client Components.

• Server Components may render Cardspark components when their props are serializable.
• Event handlers and local interactive state must originate inside a Client Component.
• Use the server-safe @cardspark/ui/utils and @cardspark/ui/market entrypoints for helper code that runs only on the server.

Load the token layer first, a theme second, and the component stylesheet last. Import them once near your application root.

1import "@cardspark/ui/tokens.css";2import "@cardspark/ui/themes/basement.css";3import "@cardspark/ui/styles.css";

Basement is the bundled default theme. Load custom theme overrides after these imports so their semantic --cs-* variables win the cascade. See Theming for scoped themes and component overrides.

Import a component from its workflow lane and pass it stable card identity. If this tile renders with the Basement theme, package and stylesheet setup are complete.

Lugia V

$214.75

SITSilver Tempest#186Card #186 of 195SIRSpecial Illustration Rare(NMNear Mint)

▲5.4%▲ $11.00

1import { CardTile } from "@cardspark/ui/core";2 3const card = {4  id: "swsh12-186",5  name: "Lugia V",6  set: "Silver Tempest",7  setCode: "SIT",8  number: "186/195",9  rarity: "Special Illustration Rare",10  condition: "Near Mint",11  marketValue: "$214.75",12  delta: "+5.4%",13  imageUrl: "https://images.pokemontcg.io/swsh12/186_hires.png"14};15 16export function ExampleCard() {17  return <CardTile format="market" card={card} tone="neutral" />;18}

View Code

Prefer lane imports in application code so dependencies communicate the workflow they serve. The root @cardspark/ui entrypoint re-exports every lane for convenience.

1import { CardTile, FilterBar } from "@cardspark/ui/core";2import { CollectionSummary, SetSummary } from "@cardspark/ui/collecting";3import { CardList, CardDetail } from "@cardspark/ui/layouts";4import { resolveMarketHistoryDataSet } from "@cardspark/ui/market";5import { formatConditionLabel, formatCurrency } from "@cardspark/ui/utils";

• core contains reusable card, metadata, and filter primitives.
• collecting contains ownership, collection summary, and set-progress surfaces.
• layouts contains composed product surfaces such as CardList and CardDetail.
• market contains server-safe market-history selection helpers.
• utils contains server-safe condition and USD formatting helpers.

Next.js App Router: import the global styles from app/layout.tsx. Add a "use client" boundary where callbacks or interactive state originate.

1"use client";2 3import { CardTile } from "@cardspark/ui/core";4 5export function InteractiveCard({ card }) {6  return <CardTile format="market" card={card} onClick={() => {}} />;7}

Vite and standard React: import the same three styles from your root entry module, such as src/main.tsx. No framework-specific Cardspark plugin is required.

Cardspark currently targets Pokémon collection interfaces, collection and set-progress workflows, USD market presentations, composed card layouts, and CSS-token theming.

• Canonical card data requires a stable id and name; arrays use the ID for React identity.
• Values such as marketValue, price, and costBasis are currently preformatted USD display strings.
• Additional games, currencies, and locale-aware value adapters are outside the current package contract.

@cardspark/ui is distributed under the PolyForm Noncommercial 1.0.0 license. Review the license before adopting the package for a commercial product.

• Components are unstyled: confirm that all three CSS entrypoints are imported once and in the documented order.
• Next.js rejects an event handler: move the interactive wrapper behind a "use client" boundary.
• An export cannot be resolved: use one of the documented root, core, collecting, layouts, market, or utils entrypoints.
• Server-only code pulls in UI: import helpers directly from @cardspark/ui/utils or @cardspark/ui/market.