1. Docs
2. Guides
3. Transparency

Velin Transparency Framework 1.2.1 beta

Labeling and provenance for web content — AI is one pillar, not the product. Deutsch: Transparenz-Leitfaden

When to use

• Machine-readable disclosure plus visible marks for AI, trust, compliance, or content metadata.
• CLI audits (transparency doctor) and migration for existing sites.

When not

• Do not treat the overlay as the source of truth — Registry / export hold provenance.
• Do not invent claim strings; use the namespaced taxonomy.

Live examples

Same attribute bridge the CLI audits. Marks are rendered at runtime; provenance stays on the host / in the registry.

AI-generated media

Preview HTML

Generated + human-reviewed · badge

Assisted · ribbon

Copy

<figure
  velin-transparency
  velin-transparency-id="hero-image"
  velin-type="ai"
  velin-status="generated"
  velin-review="human-reviewed"
  velin-created-at="2026-08-01"
  velin-approved-by="Sebastian"
  velin-license="CC BY 4.0"
  velin-source="/logs/hero.json"
  velin-version="1.2.1"
  velin-label="AI generated"
  velin-overlay="badge"
  velin-position="top-right">
  <img src="/hero.png" alt="Hero">
</figure>

Trust & official

Preview HTML

Official brand asset · verified

Release notes block

Footer renderer attaches a full-width provenance strip under the host.

Compliance / metadata · footer

Copy

<img
  src="/logo.svg" alt="Brand"
  velin-transparency
  velin-type="trust"
  velin-status="verified"
  velin-review="verified"
  velin-license="MIT"
  velin-label="Official"
  velin-overlay="badge"
  velin-tone="verified">

<article
  velin-transparency
  velin-type="compliance"
  velin-status="verified"
  velin-review="human-reviewed"
  velin-license="MIT"
  velin-overlay="footer">
  …
</article>

Renderer variants

Preview HTML

overlay

icon

panel (shows details)

Inline next to copy:

Copy

<!-- velin-overlay: badge | overlay | ribbon | icon | panel | tooltip | footer | inline -->
<img velin-transparency velin-overlay="overlay" velin-position="bottom-right" …>
<img velin-transparency velin-overlay="icon" velin-position="top-left" …>
<span velin-transparency velin-overlay="inline" velin-label="AI assisted" …></span>

Boot the marks

VelinTransparency.enhanceAll(document.getElementById('main-content'));

import { VelinTransparency, createTransparencyEngine } from '@birdapi/velinstyle/transparency';

VelinTransparency.enhanceAll(document);
VelinTransparency.attach(el, {
  type: 'ai',
  status: 'assisted',
  review: 'human-reviewed',
  provenance: { createdAt: '2026-08-01', license: 'MIT' },
});

const engine = createTransparencyEngine({ policy: {} });
await engine.doctor(html, { file: 'index.html' });

Vision

Transparency and provability are first-class. Labels answer what the user sees. Provenance answers who, when, approval, source, license, and public version.

Architecture

Engine → Providers → Registry → Validator / Doctor → Reporter / Export → Renderer.

Import: @birdapi/velinstyle/transparency

HTML quickstart

Prefer the live examples above. Minimal host:

<img
  src="/hero.png" alt="Hero"
  velin-transparency
  velin-transparency-id="hero-image"
  velin-type="ai"
  velin-status="generated"
  velin-review="human-reviewed"
  velin-created-at="2026-08-01"
  velin-approved-by="Sebastian"
  velin-license="CC BY 4.0"
  velin-source="/logs/hero.json"
  velin-version="1.2.1"
  velin-overlay="badge"
  velin-position="top-right">

JS API

import { VelinTransparency, createTransparencyEngine } from '@birdapi/velinstyle/transparency';
VelinTransparency.attach(el, { type: 'ai', status: 'assisted', review: 'human-reviewed' });
const engine = createTransparencyEngine({ policy: {} });
await engine.doctor(html, { file: 'index.html' });

Policy

Strict media rules via examples/transparency.policy.json and --policy. Soft defaults keep velinstyle check non-breaking.

Claims

ai.generated, ai.assisted, review.human, review.verified, security.checked, accessibility.checked, license.*, privacy.gdpr, content.*, version.current, custom.*.

CLI

velinstyle transparency doctor [path] --policy examples/transparency.policy.json
velinstyle transparency validate [path]
velinstyle transparency report [path] --out transparency-report
velinstyle transparency export [path] --format json-ld -o out.json
velinstyle transparency migrate [path]
velinstyle transparency migrate [path] --apply

velinstyle review / check include Transparency pillar scores.

Providers & priority

Default: api → json → meta → html. Custom: registerTransparencyProvider.

Renderer

badge, overlay, ribbon, inline, footer, panel, tooltip, icon (+ aliases). See renderer variants.

Accessibility

Marks use role="note" and a screen-reader summary of label, claims, and provenance.

Roadmap

Editor, LLM suggest hook, signed attestation, full CMS providers, analytics.