Cards.js Theming & Internationalization

1. The default stylesheet — a finished card face you import and use as-is.
2. Your own CSS — override custom properties, or re-declare any rule, on the documented DOM recipe.
3. The theme option — text styling that carries into the revealed value frames.

​

The default stylesheet

import '@dakota-xyz/cards-js/styles.css';

​

The DOM recipe

<div class="dk-card">
  <div class="dk-card__pan" id="pan"></div>
  <div class="dk-card__row">
    <div class="dk-card__group">
      <span class="dk-card__label">VALID THRU</span>
      <span class="dk-card__expiry"><span id="mm"></span>/<span id="yy"></span></span>
    </div>
    <div class="dk-card__group dk-card__group--cvv">
      <span class="dk-card__label">CVV</span>
      <span id="cvv"></span>
    </div>
  </div>
</div>

<!-- e.g. inside .dk-card__pan -->
<span class="dk-field" data-dk-field="pan">
  <span class="dk-field__masked">•••• •••• •••• 4242</span>  <!-- shown when masked -->
  <span class="dk-field__frame" hidden>…iframe…</span>        <!-- shown when revealed -->
</span>
<span class="dk-live" aria-live="polite"></span>              <!-- reveal/mask announcements (pan only) -->

​

The style contract

​

Custom markup (the headless hook)

1. Never display:none a hidden frame host. Browsers deny rendering to display:none subtrees, and the card-data processor’s frames only finish mounting once they render. Hide with visibility: hidden and keep the box, as the default stylesheet does.
2. Explicitly size visible frame hosts — with slack. An auto-sized host lets the frame fall back to the browser’s default iframe dimensions (300×150). An exactly-fitted one lets fractional rounding overflow the embedded page, and its own scrollbars render over the digits. Give every frame a text-line height and a per-field width, each a few pixels larger than the text needs.
3. Host height must cover the captured line-height. The frames copy each host’s computed text styles (see below). If the host box is shorter than that line box, the digits clip at the bottom.
4. Re-anchor inline placements while revealed. A revealed .dk-field has no text baseline, because the masked glyphs are hidden. A widget placed inline next to text therefore aligns by its bottom edge, and the digits ride high. Center it on the line instead: .dk-field:has(.dk-field__masked[hidden]) { vertical-align: middle }.

​

Restyle with CSS

.dk-card {
  --dk-card-bg: #0b1f3a;
  --dk-card-fg: #ffffff;
  --dk-card-muted: #93a4bd;
  --dk-card-radius: 12px;
}

​

The theme option

const card = cards.cardDetails({
  last4: '4242',
  theme: {
    color: '#ffffff',
    fontFamily: 'Barlow, system-ui, sans-serif',
    fontSize: '28px',
    fontWeight: '600',
    letterSpacing: '0.06em',
  },
});

• They must be concrete. The values are serialized into the frame documents, where your page’s CSS custom properties do not exist. A var() reference is rejected, and the handle throws an invalid_theme error at creation. Resolve design tokens to literal values before you pass them. In React, the handle is created while mounting, so the throw surfaces as a component error that your nearest error boundary catches.
• Fonts must be available inside the frames. The frames load no webfonts, so name widely-available families with a generic fallback, rather than your brand’s loaded font: 'Courier New, monospace', not a webfont-only family.

​

Internationalization

const card = cards.cardDetails({
  last4: '4242',
  strings: {
    validThru: 'VÁLIDO HASTA',
    cvvLabel: 'CVV',
    panPlaceholder: '•••• •••• •••• {last4}',
    revealedAnnouncement: 'Detalles de la tarjeta visibles',
    maskedAnnouncement: 'Detalles de la tarjeta ocultos',
  },
});