API Design Rules — Quick Reference

Full docs: documentation/dev/api-design.md and documentation/dev/adding-apis.md.

Read those first. This file highlights the key points for quick reference during the add and review workflows.

Naming

• Match Skia's upstream C++ type name — don't invent names
• SK prefix for core, GR for GPU, GRGl/GRVk/GRMtl/GRD3D for backends
• Full words (SetVariationCoordsDesign, not SetVarCoordsDesign)
• File named after primary type, file-scoped namespace

Properties vs Methods

• No params + returns data → property (VariationAxisInfos, GlyphCount)
• Takes params (including Span) → method (GetVariationAxisInfos(Span<>))

Span Triple

Every array API needs three members:

1. T[] Property — convenient, allocates
2. int PropertyCount — for pre-allocating Span
3. int GetProperty(Span<T>) — allocation-free

Input Parameters

• ReadOnlySpan<T> not T[] — accepts arrays, spans, stackalloc
• ref struct parameter bag for many optional params

ABI

• Overloads, not defaults
• Deprecate, don't remove

C API

• DEF_MAP for layout-compatible structs, manual converter for others
• static_assert in sk_structs.cpp for every DEF_MAP
• #include the C header in sk_types_priv.h before DEF_MAP
• New typedefs → define in C, map in libSkiaSharp.json

Tests

• Exact values from known fonts
• Span vs array equivalence
• Interop round-trip (data survives P/Invoke)
• Static font returns empty, not null/crash
• Negative index throws ArgumentOutOfRangeException
• Standalone types get own test file

Don't

• No XML doc comments (generated by separate process)
• No #nullable disable unless needed
• No fabricated fonts — use real fonts
• No early returns that hide test failures

Gallery Samples

• Standalone features get a new sample file in samples/Gallery/Shared/Samples/
• Small enhancements update existing samples with new controls
• Internal/plumbing APIs don't need samples
• Samples teach the API — clarity over performance
• Interactive controls (sliders, pickers, toggles) for exploring parameters
• Real assets only, loaded via SampleMedia
• Dispose everything (using or OnDestroy)