Notation & Conventions

A Grammar for Visual Composition

Neural Sketch is more than a collection of macros. It’s a structured language for communicating visual ideas with clarity and repeatability.

At the heart of this language lies a deliberate naming system—one that blends $\LaTeX$ ’s expressive power with modern design sensibilities. Its aim is to reduce friction, invite readability, and encourage composition over micromanagement.

Names that Mean Things

Every macro in Neural Sketch begins with a clear prefix: \nsk. This signals intent and origin, and ensures zero namespace collisions. Beyond the prefix, macro names follow PascalCase, while parameters (or keys) use kebab-case.

\nskBlock[
  fill=nskRed,
  border-radius=2mm,
  text-center=Central Node,
]

Pattern: Command as Action

Each macro fits a predictable shape:

\nsk<action>[<key-value pairs>]{<optional content>}

action identifies what you're drawing or composing—Block, Container, Group, Annotate, etc.
key=value pairs configure styling, geometry, positioning, text, and behavior.
optional content is passed optionally—for structures like containers, groups, or figures.

Keys must be separated by commas. Avoid blank lines within [ ... ], or the parser will raise a syntax error. The { ... } content block, however, may span multiple lines freely.

Why Not Environments?

You might expect $TikZ$ -style environments:

\begin{nskBlock}[...]
\end{nskBlock}

But Neural Sketch intentionally rejects this form.

Instead, every component is a macro.

\nskBlock[...]

This choice is not just stylistic—it’s structural. It enables:

Inline composition (nesting without verbosity)
Declarative control (no need for paired delimiters)
Lisp-like clarity (everything is a function, every part composable)

Macro-Based (`\nskBlock`)	Environment-Based (`\begin{nskBlock}`)
Stateless, composable ✅	Stateful, rigid ❌
Minimal nesting ✅	Deeply nested ❌
Better suited to key–value configs ✅	Harder to modularize ❌

A diagram should be as easy to write as it is to see.

Safe & Expandable Forms

Many Neural Sketch commands come in two complementary forms:

The standard (safe) version: \nskBlock
The expanded (args-aware) version: \nskBlock*

The starred form allows you to pass custom-defined macros and dynamically constructed key-value lists—perfect for repeated patterns or conditional configurations.

% Define a common style for cyan-highlighted blocks
\def\cyan{fill=nskStrongCyan!20, border-color=nskStrongCyan}
 
% Use it with the expanded form:
\nskBlock*[id=ablock, \cyan]

This mechanism enables powerful abstraction:

write once, reuse often
pass partials or macros into your diagrams
programmatically construct style bundles

The * doesn’t mean “more danger.” It means “more trust.” You’re opting into lower-level control, with the freedom to shape the interface around your own reuse patterns.

Styling Conventions: A Few Simple Rules

To maintain visual and semantic harmony across diagrams:

Macro names use PascalCase: \nskBlock, \nskContainer, \nskFigure
Keys use kebab-case: fill=nskBlue, border-radius=3mm
Color tokens are always prefixed with nsk and follow camel–Pascal style: nskBlue, nskLightGray, nskMainAccent

This gives you a visual rhythm—fast to write, easy to read.

Recommended Workflow

Neural Sketch is structured around a clear, repeatable pattern. Here's how most figures begin:

Load the Package and Modules

Import Neural Sketch in your preamble. Load only the modules you need, or use * to load all:

\usepackage{neural-sketch}
\nskUseModule{*}

(Optional) Set Global Styles.

Global styles let you control how your blocks and containers behave project-wide:

\usepackage[
  block-width=2.5cm,
  block-height=1.5cm,
  container-fill=nskRed!60,
]{neural-sketch}

Compose Your Diagram

Once your primitives and styles are in place, define your figure declaratively:

\begin{nskFigure}
  \nskContainer[text-north=Grouped Blocks]{
    \nskBlock[x=0, y=0, text-center=A]
    \nskBlock[last-pos={right=}, text-center=B]
  }
\end{nskFigure}

Final Thought

The purpose of Neural Sketch’s naming conventions is not just to avoid confusion—but to encourage flow. You should be able to think structurally, write visually, and render precisely—without getting lost in syntactic weeds.

Good notation makes good ideas legible.

\nskBlock[
  id=core,
  text-center=Diagram as Code,
]
\nskBlock[
  id=aux,
  text-center=Composable Companion,
]
 
\nskConnect[from=core, to=aux]

And that’s the whole point.

Notation & Conventions

On this page