This question comes up a bunch of times. It would be great to have documentation explaining why and how it works.

The main issue is that if you have a file under:

  package:a
    lib/a/b/c/d.html

and you want to import

  package:b
    lib/e/f.html

Then you need to write:
    href="../../../../../packages/e/f.html"

There are many cases that are slightly confusing that would be good to highlight in the docs:
 - from web to lib (even in the same package): packages/pname/f.html
 - from web/foo to lib: ../packages/pname/f.html
 - from lib to lib: ../../packages/pname/f.html
 - from lib/foo to lib: ../../../packages/pname/f.html

We should also highlight how this works and why we do it. Here are some of the details:
  - it needs to work in Dartium without any code transformation: resolving the path in the context of a simple-http-server should yield a valid path to the files. For now we can only assume that we can use a packages/ directory that is in web/packages

  - it needs to be canonicalizable: we might need to fix this further, but right now we do a lot of effort to make sure that if you have

      <link rel=import href=packages/a/a.html>
      and a.html has <script src=a.dart>
      and the entrypoint also loads "package:a/a.dart"

  Then both versions of a.dart are loaded from the same URL.

  We can only do this kind of canolicalization if we convert packages/a/a.dart into package:a/a.dart under the hood. We do so by detecting the package-pattern in the html-import urls.

  - it needs to continue to be valid after we compile the application. We could normalize the imports in our transformations, but given all the other restrictions we have above, we just keep them as they are.