I've seen the confusion come up more than once that @builtin(position) in a vertex shader and @builtin(position) in a fragment shader are not the same thing. I'm wondering if the WGSL docs on builtins could be refactored to maybe help. As it is it just names all the builtins in a table.

But, another way to look at, imagine we had 2 TypeScript functions

type VertexInputs = {
  vertex_index: number;
  instance_index: number;
};
type VertexOutputs = {
  position: [number, number, number, number];
  clip_distances?: number[];
};

function processVertices(userFn: (inputs: VertexInputs) => VertexOutputs);

type FragmentInputs = {
  position: [number, number, number, number];
  front_facing: bool;
  sample_index: number;
  sample_mask: number;
};
type FragmentOutputs = {
  frag_depth: number;
  sample_mask: number;
}

function processFragments(userFn: (inputs: FragmentInputs) => FragmentOutputs);

A user can write a function:

function vs({vertex_index)} {
  const v = [
    [0,1,0,1],
    [-1,-1,0,1],
    [1,-1,0,1],
  ]
  return {position: v[vertex_index]};
}

With the code above, there is no ambiguity that position returned from a function passed to processVertices has anything to do with position passed to a function in processFragments

It would not be common to document VertexInputs, VertexOutputs, FragmentInputs, and FragmentOutputs mixed together in a table.
They would likely each be documented separately. I don't know that that would solve the confusion since most people see WGSL first, not the docs. But still, the way it's documented now, with them all together in a single table, might be better separated into 5 tables (vertex inputs, vertex outputs, fragment inputs, fragment outputs, compute inputs)? Or something else?