Skip to Content
Vektos
Anecdotes

The ideal answer was not

Five hand-written reference solutions graded clean on the first try and still failed lint in twelve places.

What happened

Every benchmark task needs a reference solution: a page written by hand, with the design system, that proves the task can be done cleanly. I wrote five, carefully, with the components and tokens I had designed the day before. The task test ran each one through gradeSource. All five came back with zero violations on the first try.

Then bun run check ran oxlint on them:

  • 5 errors from @pandacss/file-not-included: the tasks/ folder was not in the Panda config's include, so none of the styles would have been generated. The pages would have rendered unstyled.
  • 1 error from jsx-a11y/prefer-tag-over-role: a <p role="status"> where <output> is the native element.
  • 2 warnings from @pandacss/no-physical-properties: pt and borderTopWidth in a total row, where the design system expects paddingBlockStart and borderBlockStartWidth.
  • 4 warnings from no-unsafe-type-assertion: status as keyof typeof badges. JSON imports type "status": "pending" as string, and the quickest way back to a union is a cast.

Twelve problems in code the graders called perfect, written by the person who wrote the graders.

What we learned

The graders answer one question: is every style value a token used for its job? They do not know about logical properties, accessibility patterns or Panda's own configuration, and they should not: they must work on any stack. Lint knows all of that for this stack. The two measure different things, and a clean grade on one says nothing about the other.

The type casts are a quieter lesson. The fixture shape pushed the code toward a cast. Nothing about the design system was wrong; the data simply did not carry its types. An agent will make the same move, and a type-aware lint will count it.

What it means for Vektos

  • oxlint has to be a grader, as PLAN §4 already says ("oxlint + Panda rules (JSON output)"). Without it, a run can score zero and still ship unstyled or inaccessible markup. It goes in with tsc and axe in the grader block.
  • The reference solutions are now checked by everything an agent's code will be checked by: graders in the task test, tsc and oxlint in bun run check. That is the only way "the ideal answer" means something.
  • Fixtures shape the score. Wide JSON types cost lint warnings in every answer. That is fine as long as it is the same for every run, but a report should not blame the context for it.

Follow-ups

  • Add an oxlint grader that runs the Panda rules and reports JSON, in week 2.
  • Decide whether no-unsafe-type-assertion counts as a design-system violation or as general code quality. Probably the second, reported apart.
  • Consider shipping a fixture.d.ts with each task so the data has real unions.

On this page